Ira Goldklang’s TRS-80 Revived Site » NEWDOS/80 v2.0 Reference

NEWDOS/80 v2.0 Reference – Disk Basic and Included Programs

by Ira @ 11:10 am on May 14, 2009.

NEWDOS/80 v2.0 Reference – Disk Basic and Included Programs

7. DISK BASIC, NON-I/O ENHANCEMENTS

7.1. INTRODUCTION, Requirements

For NEWDOS/80 most, but by no means all, of the interface specifications between BASIC and the BASIC programmer remain the same as for DISK BASIC under TRSDOS 2.3 on the Model I and for TRSDOS 1.3 on the Model III. The NEWDOS/80 BASIC user is expected to have and be knowledgeable of both the non disk BASIC manual and the disk BASIC portions of the TRSDOS manual for whichever of the two TRS-80 models is being used. The current and next chapters of this NEWDOS/80 version 2 documentation discuss only the differences from the TRS versions. Both the Tandy manuals are excellent; if they didn’t come with your TRS-80 when you bought it, buy them!!!! Apparat does not, in this manual, duplicate their contents.

7.2. General comments

When a BASIC syntax error occurs, BASIC does not automatically enter EDIT on the offending text line, but it does set that line as the current line. If the operator wishes to edit the line, press comma. This change is to make it more difficult for the operator to inadvertently clear variables that he/she would otherwise want to see to assist in debugging.

BASIC programs may disable the BREAK key via CMD”BREAK,N”, and re-enable it by CMD”BREAK,Y”.

Because CLOAD does a NEW function between consecutive bytes from tape, it will lose synchronization if BASIC is running with more than 3 file areas.

When a DOS error is encountered by BASIC and if no ON-ERROR routine is active, both the DOS error message and the BASIC error message are displayed.

BASIC now has a total of 8 overlays that it uses. The user will notice that disk I/O occurs whenever RUN is executed and whenever execution is interrupted (STOP, error or BREAK) or terminated (END); this is done to bring in BASIC routines needed for the current or anticipated next function.

NEWDOS/80 DISK BASIC does NOT allow text line deletion to be done by simply typing in the line number. The explicit delete command, DELETE or D, must be used.

7.3. Activating DISK BASIC

DISK BASIC is activated by keying in one of the following commands to DOS:

BASIC

BASIC n

BASIC m

BASIC cmd

BASIC n,m,cmd

BASIC m,n,cmd

BASIC n,m

BASIC m,n

10.

BASIC n,cmd

11.

BASIC m,cmd

where:

	*	means the user wants BASIC to reinstitute the program in the text buffer, using the same values for m and n as appear to exist in main memory. This allows the user to recover from an unwanted ‘reset’ or to get back to the same program after a CMD”S”. If BASIC is able to accomplish this, it forces ‘LIST’ as its first command. If BASIC is unable to reinstitute the program, it exits to DOS READY. BASIC * will not work if n was less than 2 or if the program was less than 3 lines.
	n =	the number of fileareas that BASIC is to allocate, default = 3, maximum = 15. This is the highest fan (filearea number) that will be used in any statement during this invocation of BASIC. If the BASIC program is to use field item files with standard record length not equal to 256, then n must be specified and must be suffixed with the character V (see example 4 below).
	m =	memory size. The value m minus 1 is the highest memory location that BASIC is allowed to use. If m is not specified, the current DOS HIMEM value is used. All memory m and above is not used by BASIC and can be used for other routines such as printer drivers, special code USR routines, etc.
	cmd =	one line of BASIC text, consisting of one or more BASIC statements. This text line is considered direct keyboard input and will be executed as soon as initialization is completed.

Remember, the DOS command activating BASIC is limited by DOS to a maximum of

80 characters, including ENTER, and it is further limited to 32 characters, including ENTER if invoked via ‘AUTO’.

Any error encountered during initialization causes a return to DOS.

If DOS is in RUN-ONLY state, the DOS command activating BASIC must contain a RUN or a LOAD (option R) statement.

Examples:

BASIC Brings up BASIC with 3 file areas, high memory set to the current value for HIMEM in DOS and displays ‘READY’, waiting for the operator’s command.

BASIC,RUN”XXX/BAS” Brings up BASIC with 3 file areas, high memory set to the current DOS HIMEM value, loads BASIC program XXX/BAS into the text area and starts its execution.

BASIC,9,48152,LOAD”XXX/BAS” Brings up BASIC with 9 file areas, high memory set to 48151 (1 less than 48152), loads BASIC program XXX/BAS into the text area and displays ‘READY’, waiting for the operator’s command.

BASIC,3V This works the same as example 1 above, except that each of the 3 files areas is assigned an extra 256 byte buffer. This extra buffer per filearea is needed if the program will be using field item files with a record length other than 256.

BASIC,CLEAR3000:A=1:RUN”XXX”,V Brings up BASIC with 3 fileareas, sets its high memory value to DOS’s current HIMEM value, performs CLEAR reserving 3000 bytes for the string area, sets numeric variable A equal to 1, loads BASIC program XXX and commences its execution without clearing the variables, thus leaving variable A intact for the program to inspect.

7.4. Direct Scrolling/Editing Commands

NEWDOS/80 DISK BASIC allows the following ‘direct’ commands:

	. (period)	LIST the current text line.
	down-arrow	LIST the next text line. If there is no next text line, performs as / .
	up-arrow	LIST the text line before the current line. If none, performs as ; .
	; or shift-up-arrow	LIST the first text line.
	/ or shift-down-arrow	LIST the last line in text. Users having the newer ROM will find that shift-down-arrow is no longer a usable key; hence the need for / .
	:	Scroll one display page toward the start of the text. When done, the previous current text line is now at the bottom of the display excepting that if the previous command was . or @ , the previous display’s top line is now the new display’s bottom line. The new current text line is the bottom line on the new display.
	@	Scroll one display page toward the end of text. When done, the previous current text line is now the at the top of the display, and the new current text line is the bottom text line on the new display.
	, (comma)	EDIT the current text line.

Only 1 such command per direct statement line, and the command, to be seen, must be the first character of the input line (no line number or backspacing allowed).

7.5. Text Editing Command Truncation

NEWDOS/80 DISK BASIC allows the truncation of the commands AUTO, DELETE, EDIT and LIST to A, D, E and L respectively when the following conditions are met:

1st character of the input line.

Followed by either a period or a decimal digit.

The input line does not contain an =.

7.6. DI and DU text editing functions

DI and DU Two additional BASIC text editing functions are implemented using the following forms of direct command:

DI aaaaa,bbbbb

DI .,bbbbb

DU aaaaa,bbbbb

DU .,bbbbb

where:

	aaaaa	is the line number of the text line to be moved or duplicated, and
	bbbbb	is the line number to be given the moved text line or the duplicate of the text line.
	DI	means to delete the line at aaaaa and insert it at bbbbb.
	DU	means insert at bbbbb a duplicate of the text line at aaaaa, but do not delete the line at aaaaa.
	Text referring to aaaaa is not altered to refer to bbbbb. If this is desirable, then use RENUM to move the text line.
	The use of a period in place of aaaaa causes aaaaa to default to the last line listed, edited or deleted.

7.7. RUN and LOAD (optionally retaining variables)

RUN and LOAD may now optionally retain all variables and open fileareas by using the V option in the following formats:

RUN “filespec1″,V

LOAD”filespec1″,V

where filespec1 is the filespec of the program file being executed. The LOAD with the V option executes exactly the same as the RUN with V option. The RUN with V option preserves all the variables, excepting DEFFN variables, during the execution of RUN; thus the variables existing before the RUN statement can be used after the RUN statement. Any fileareas open prior to the RUN are left open for use after the RUN statement. If the V option is specified, the R option may not be. See example 5 in section 7.3.

7.8. MERGE Dynamic loading of overlay program

The MERGE statement has been expanded:

MERGE will merge either an ASCII or a packed text file.

MERGE may be executed as a direct statement or as a program statement.

If MERGE is executed as a program statement, the MERGE statement must not be part of a DEFFN statement, a subroutine or a FOR-NEXT loop (as a POPS function is implicitly performed), must be the last statement of the text line, must be followed by the text line where execution will continue after the MERGE, and the merge file must not contain a line whose number is the same as the number of a text line existing at the start of the execution of the merge (use CMD”F”,DELETE to delete conflicting text lines before executing the MERGE). The merge protects all variables. The user must assure enough main memory space is available for the merge as error recovery is not possible if the merge fails once actual merging commences. Example:

100 MERGE”XXX/BAS”

110 X=1 execution continues here after the MERGE is completed

7.9. RENUM Renumber the Current BASIC Program.

RENUM sssss,iiiii,ppppp,qqqqq[,U][,X]

RENUM ,

RENUM U

RENUM X

RENUM U,X

The current BASIC program or a part of it may be renumbered while it resides in the text area. Via the U option, the RENUM does not actually perform renumber but only does its text error checking, thus allowing the undefined line numbers and some, but not all, syntax errors to be found. The user may, by proper choice of the new line number values, move a portion of the program to a different place in the program with all references to any of the moved lines changed to the new lines numbers. Lastly, via the X option, RENUM will not declare as an error any undefined line number if that line number lies outside of the range of lines being renumbered, thus allowing a program to have references within it to lines that are intentionally not part of the program.

The basic renumber command causes all text lines whose line numbers are greater than or equal to ppppp and less than or equal to qqqqq to be assigned new line numbers. sssss is the first new line number assigned with subsequent numbers generated by adding iiiii to the line number of the previous text line. sssss and iiiii must be in the range 1 – 65529 and have default value 10. ppppp must be in the range 1 – 65529, has default value 0. qqqqq must be in the range 1 -65529, greater than or equal to sssss, and has default value 65529. The range of newly generated line numbers must not encompass any old text lines that are not part of the resequenced range ppppp – qqqqq inclusive. So long as this rule is observed, the newly generated line number range may be placed anywhere in the text with the renumbered text moved to the proper new text location.

At least one parameter must be specified. If the user wants to specify all defaults and neither X nor U, then use a comma as the only parameter.

For the series sssss,iiiii,ppppp,qqqqq, if one or more of the 4 numbers are to use the default values, then commas must appear in the proper place to indicate which of the 4 values a given line number is for. See example 4 below.

If the U option is specified, the text is not altered in any way and RENUM simply searches text for undefined line numbers and for some errors associated with BASIC statements that use line numbers. These errors are displayed in the following format:

	sssss/U – there is no text line sssss.
	sssss/X – text line sssss has syntax error.
	sssss/S – text line sssss has a bad line number.

If the X option is specified, references to non-existent text lines are not displayed as errors if that line number is also outside of the ppppp to qqqqq range. The X option is intended as aid to programmers who use a base program and overlay programs which refer to text lines in each other.

If any error is encountered before text is altered, the command reverts to performing as if the U option had been specified and displays all the errors it can find. If an error is encountered after text alteration begins, ‘FATAL ERROR. TEXT NOW BAD’ is displayed and the 4030H exit taken to DOS. The BASIC text must not be reclaimed (don’t use BASIC *).

If either SYS11/SYS or SYS13/SYS are not in the system when RENUM is executed, the system will exit to DOS READY (see section 5.5).

RENUM will refuse to renumber a program whose first text line’s number equals 0. Use ‘DI’ to assign the line a number other than 0. Examples:

RENUM U The BASIC text is checked for undefined line numbers and other errors that would normally be encountered in an actual renumber. The BASIC text is not altered.

RENUM , The entire BASIC text is renumbered using an increment of 10. The first text line is assigned line number 10, the 2nd assigned line number 20, and so on.

RENUM 100,100 The entire BASIC text is renumbered using an increment of 100. The first text line is assigned line number 100, the 2nd is assigned 200, and so on.

RENUM 2050,,2050,3160 All text lines from and including any line numbered 2050 to and including any line numbered 3160 are renumbered using an increment of 10. The first renumbered line is assigned line number 205$, the second is assigned 2060, and so on.

RENUM 30000,5,15365,18112 All text lines from and including any line numbered 15365 to and including any line numbered 18112 are renumbered using an increment of 5. The first renumbered line is assigned line number 30000, the 2nd is assigned 30005, and so on. The renumbered text lines are moved to the new positions in the text.

7.10. REF List references to variables, line numbers and keywords

The BASIC statement REF allows the BASIC programmer to find all places in the program where a line number, an integer, a variable, a string, a function code, a packed sequence of characters or an unpacked sequence of characters is referenced. REF has the following formats:

REF* Display full reference list for all line numbers, integers and variables.

REF$ Print on the printer a full reference list for all line numbers, integers and variables.

REFnn Display all references to the variable(s) named nn. If nn is only 1 character, a blank is assumed for the second. nn may not be more than 2 chars and must not have a type suffix.

REFsssss Display all references to the line number and/or integer sssss where sssss is a 1-5 decimal digit number between 0 and 99999. Hexadecimal or octal references within the text are not listed.

REF*nn

REF$nn

REF*sssss

REF$sssss

REF Display the next text line containing at least one reference to the variable or number specified by the last REFnn or REFsssss statement executed. If there are no more referencing text lines, ‘TEXT END’ will be displayed. If ‘REF’ entered again, the first referencing text line will be listed. Remembrance of the search variable name or number and the current search line number within the text is usually (but not always) lost when any command involving DOS is executed.

10.

REF=xxx The character sequence xxx is packed by the standard BASIC text packing routine. The BASIC text is then searched for a match on the packed xxx value and the line numbers listed for all lines containing the packed xxx value. If the packed value xxx is more than 16 bytes long, only the first 16 packed bytes participate in the compare. This format of REF is to used when the user wants to know where in the text a BASIC function code (i.e., PRINT, LPRINT, GOTO, etc) is used. The text lines containing xxx can be displayed one at a time by repeated issuance of the format 9 REF command.

11.

REF”xxx This format operates similar to format 10 except that xxx is not packed. xxx is considered a string unless xxx itself contains a “. This format allows xxx to be found in strings and comments.

12.

REF@sssss This statement is similar to format 9 except that the search will start with 1st text line whose line number is greater than or equal to sssss.

Press BREAK to pause, ENTER to continue, and up-arrow to terminate the REF function. Formats 5-8 are the same as 1 and 2, except listing/printing starts with the specified variable name or decimal number, if it exists, or the next higher existing name or number, if not.

If SYS12/SYS is not in the system when the REF statement is executed, the system will exit to DOS (see section 5.5).

7.11. Lower Case Suppression (Model I only)

Text String Lower Case Suppression (Model I only) Users who do not have the hardware lower case modification or those that do but don’t use a lower case driver to bypass the ROM display routine will occasionally be puzzled why some string compares fail and syntax errors appear in perfect appearing statements. This is due to the acceptance of lower case letters into strings which display as upper, and the acceptance of lower case @ into text statements. Remember the ROM swaps lower case to upper and vice versa before BASIC sees the characters. In the case of data, there is nothing that can be done about this problem except to remember that if it appears equal.on the display, there still may be a lower case/upper case mismatch in memory. For text input, if system option AS = Y, text string lower case letters, but not lower case @, will be forced to upper case, eliminating many of these problems.

7.12. RUN-ONLY

For DISK BASIC there are two ways BASIC can be forced to run in RUN-ONLY mode: (1) if system option AB = Y, and (2) if the BASIC program file is password protected, passwords are enabled, the access password specified in the RUN or LOAD (option R) statement and the access level = EXEC.

If system option AB = Y, the DOS command activating BASIC must contain the necessary RUN or LOAD (option R) statement to start a program executing as the operator is not allowed to input any direct command statements.

In RUN-ONLY, the BREAK key is disabled and BASIC is inhibited from accepting direct statements (data is OK) from the operator. The program has full control, and must exercise it. A menu program can issue RUN or LOAD (option R) statements for other BASIC programs, and those programs can do the same to return to the MENU program or go on to the next program of a sequence. Optionally, a base program may remain in memory at all times, and via CMD”F”, DELETE and MERGE, bring in overlay programs as necessary. Programmers should carefully study available options under RUN, MERGE, LOAD, and CMD”F functions.

7.13. Comparisons in the use of the function CMD between NEWDOS/80 and TRSDOS.

CMD°A” Not implemented; use CMD”S”.

CMD”B” Not used on the Model I by NEWDOS/80 nor TRSDOS. TRSDOS’ Model III use is not implemented in NEWDOS/80; use CMD”BREAK,Y/N”

CMD”C” This command (1) compresses out all spaces from the program text, excepting for those within strings, and (2) deletes all remarks from the text, including entirely those lines which are entirely remarks. The statement CMD”C”,S compresses out all spaces from the program text, excepting those within strings and remarks. The statement CMD”C”,R deletes all remarks from the text, including deleting entirely those lines which were entirely remarks.

In some cases, GOTO, GOSUB, etc. refer to a text line that is entirely remarks and the deletion of remarks from the text will cause these referenced lines to disappear. The programs should be altered to have these GOTOs and GOSUBs refer to text lines that are not entirely remarks. After remarks have been deleted from a program, execute RENUM U to determine if there are any undefined line numbers resulting.

Though BASIC is designed to ignore spaces that are not in text remarks or character strings, the removal of spaces from text can still cause confusing situations. For example, compressing

10 FIELD 1,20 AS C$

20 IF F OR D THEN 10

10 FIELD1,20ASC$

20 IFFORDTHEN10

will cause syntax errors to occur for both lines during execution after either (1) the program has been stored in ASCII and then read back in or (2) the lines have been edited. To avoid these problems that may exist for weeks or months before either of the above two conditions occur, the CMD”C” function automatically unpacks each compressed text line, packs it again and compares the new packing with the old that existed before the spaces were compressed out. For any text line where the two packings are different in any way, the spaces are restored into that text line (remarks, if deleted, remain deleted) and the line’s number is listed on the display. The user may then inspect these lines and remove spaces that won’t affect the program. For any given program, there should be very few lines rejected by CMD”C”.

CMD”D” TRSDOS’ meaning is not implemented on the Model III under NEWDOS/80; use CMD”doscmd”. On the Model I, CMD”D” still invokes DEBUG though 123 is the preferable method.

CMD”E” Displays the DOS error messaged associated the latest DOS error encountered by BASIC.

CMD”F” Not used in TRSDOS. In NEWDOS/80, there are two formats:

CMD”F”,fc used when the function code fc must be findable by REF, RENUM and others.

CMD”F=fc” used when the function code fc is not to been seen by REF, RENUM, etc. or where the specially defined function code could be confused by the normal text packing routine.

These CMD”F” functions are specified in sections 7.15. thru 7.20.

CMD”I” Not used on the Model I by either NEWDOS/80 or TRSDOS. TRSDOS’ Model III use is not implemented in NEWDOS/80; use CMD”dos-cmd”.

CMD”J” Calendar Date Conversion.

CMD”J”,date1,date2

converts the expression date1 to the appropriate format and stores the result in the string variable date2. If date1 is in mm/dd/yy format, date2 is stored in ddd format and if date1 is in -yy/ddd format, date2 is stored in mm/dd/yy format where:

mm is a two digit month value between 01 and 12.

dd is a two digit day-of-the-month value between 01 and 31.

ddd is a three digit day-of-the-year value between 001 and 366.

yy is a two digit relative year-within-century value between 00 and 99. For leap year conversions, yy is assumed to be in the 20th century, i.e., from 1900 to 1999.

CMD”L” TRSDOS Model III meaning not implemented in NEWDOS/80; use CMD”LOAD,filespec”. This function is not used on the Model I.

10.

CMD”O” Array Sort; see discussion below (section 7.21.) for CMD”O”.

11.

CMD”P” Not used on the Model I. TRSDOS’ Model III meaning is not implemented in NEWDOS/80; use PEEK(&H37E8) to obtain the 0 – 255 value for the current printer status.

12.

CMD”R” TRSDOS’ Model III meaning is not implemented in NEWDOS/80; use CMD”CLOCK,Y”. On the Model I, CMD”R” still reenables the interrupts as before.

13.

CMD”S” Exit BASIC and return to DOS READY state. However, if the command is of the form CMD”S=doscmd”, then the following occur:

The DOS command doscmd is moved into the DOS command buffer.

BASIC exited.

The DOS command placed into the DOS buffer is executed immediately without an intervening DOS READY.

When that command is completed, control returns to DOS READY and not to BASIC.

14.

CMD”T” TRSDOS’ Model III meaning is not implemented in NEWDOS/80; use CMD”CLOCK,N”. On the Model I, CMD”T” still disables the interrupts as before.

15.

CMD”X” Not used on the Model I by NEWDOS/80. TRSDOS’ Model III meaning is not implemented; use the REF command.

16.

CMD”Z” Not used on the Model I by NEWDOS/80. TRSDOS’ Model III meaning is not implemented; use CMD”ROUTE,…”.

7.14. CMD”doscmd”

If the string expression associated with the CMD function has two or more characters and does not start with either “S=” or “F=”, then the string is assumed to be a command to be executed by DOS. BASIC moves the command to DOS’ command buffer, sets DOS to MINI-DOS mode, and calls DOS to execute the command via 4419H, DOS-CALL. Upon return, BASIC turns off DOS’ MINI-DOS mode. If DOS has rejected the command because it was not legal under MINI-DOS, BASIC then attempts to reissue the command to DOS under normal mode by doing the following:

If approximately 8,000 bytes are not available between the top of BASIC’s array areas and the bottom of BASIC’s stack (which is immediately below the string area), BASIC declares OM (‘OUT OF MEMORY’) error and terminates the current statement. If the space is available, BASIC moves all of memory from 5200H to 70FFH to that free area, sets itself to use stack area 7000H-71FFH and computes a checksum over the region from 7100H to the top of BASIC’s memory (takes about 2 seconds). Then it calls DOS to execute the DOS command. Upon return from DOS, BASIC moves the saved region back to 5200H-70FFH and recomputes the checksum (again, another 2 seconds). If the check fails, this means that the DOS command executed has altered some of BASIC’s bytes; BASIC cannot continue and exits to DOS with ‘BAD MEMORY’ error.

Whichever way the command was executed, BASIC now checks the return code from DOS. If an error occurred and the error message has already been displayed, BASIC terminates the CMD”doscmd” statement with ‘PREVIOUSLY DISPLAYED ERROR’ error state. If a DOS error occurred, BASIC calls 4409H to display the DOS error message and terminates the CMD”doscmd” statement with ‘DOS ERROR’ error state. If no error occurred, BASIC continues with normal processing.

Any DOS library command or assembly language program (that will execute using only the 5200H – 6FFFH region and/or a non-BASIC, non-DOS region of main memory) can be executed in this fashion. SUPERZAP and DIRCHECK are two programs that may be executed through CMD”doscmd”. FORMAT and most forms of COPY can be done; however, single drive, two diskette copies cannot be done as they require the maximum amount of memory. Also, don’t specify the UBB parameter in COPY.

Remember, DOS commands are limited to 80 characters, including the ENTER character that BASIC will append to the doscmd string when moved to the DOS command buffer.

User programs are warned to leave the Model I memory area 4080H -41FFH (Model III area 4080H – 41E2H) alone except where alteration is in conformance with BASIC’s current uses.

CMD”BASIC” should never be executed. If for some reason the programmer wants to exit BASIC and return, use CMD”S=BASIC”.

Almost all DOS commands may be executed via CMD”doscmd”. Examples:

1. CMD”DIR 1″ list a directory

2. CMD”COPY XXX:0 YYY:1″ copy a file

3. CMD”COPY 0 1 07/10/81 FMT” full diskette copy, with format

4. CMD”SUPERZAP” executes program SUPERZAP and return to BASIC

5. CMD”DO CHAINFIL” perform chain file functions and return

7.15. CMD”F=POPS”, CMD”POPR” and CMD”F=POPN”

If the statement is CMD”F=POPS”, then all returns and FOR-next controls are purged, leaving BASIC with no outstanding returns or nexts. When done, execution continues with the next statement. The purpose of this statement is to allow the programmer to ‘bail-out’ of complex coding and return to BASIC’s first level. This avoids leaving residual information in BASIC’s control stack which on recursive returns to the high level without CMD”F=POPS” will eventually cause program failure.

If the statement was CMD”F=POPR”, then the current GOSUB level is purged along with any outstanding FOR-NEXTs for that level. This is the same as return except control does not pass to the statement following the associated GOSUB, but instead passes to the statement following the CMD”F=POPR” statement.

If the statement is CMD”F=POPN”, then the most recently established FOR-NEXT’s control data is purged. This is the same as ‘NEXT’ where the loop limit is exceeded. Execution continues with the statement following the CMD”F=POPN” statement.

If the statement is CMD”F=POPN” vu where vn is a variable name, the FOR-NEXT loop associated with vn is purged along with any other FOR-NEXT loops established while vn’s loop was outstanding. Execution is the same as for ‘NEXT vn’ when the loop is to end. Execution continues with the statement following the CMD”F=POPN” vn statement. The purpose of CMD”F=POPN” is to allow breaking out of a loop while not leaving residual loop control information that can confuse the programmer if he/she subsequently uses FOR-NEXT variables in reverse order.

7.16. CMD”F=SASZ”

Change BASIC’s string area size without affecting or clearing the variables.

CMD”F=SASZ”,exp1

allows the string area size to be changed without clearing the variables. exp1 must be a value large enough allow the string area to contain the strings that it contains when the statement is executed. An error will be generated if exp1 is too small or is too large (i.e., will cause overlap with the text, scalar and array areas). Example:

CMD”F=SASZ”,4000

7.17. CMD”F=ERASE” and CMD”F=KEEP”

Selective clearing of BASIC variables.

CMD”F=ERASE”,vn1,vn2,vn3… allows the specified variables to be cleared. If a specified variable is within an array, the entire array is cleared. The size of the string area is not changed. This statement should be used when an array is no longer needed or the user wishes to redimension it by a subsequent DIM statement. This statement may be multi-text lines as described for CMD”F=KEEP” below.

CMD”F=KEEP”,vn1,vn2,vn3… causes all variables to be cleared except those specified and except specially defined variables such as those defined by a DEFFN statement. The size of the string area is not changed. If no variable names are specified, all variables are cleared, except the special ones. If a specified variable name is within an array, the entire array is exempted from the clear. The statement may specify as many varfable names as desired with overflow from one text line to the next noncomment text line taking place whenever the last variable name of a text line is followed by a comma. Example:

CMD”F=KEEP”,A$,B%,C,D#, ‘statement first line

E!,F,G$, ‘statement 2nd line

REM this line is bypassed

H!,I ‘statement last line

7.18. CMD”F”,DELETE

Dynamic deletion of text lines:

CMD”F”,DELETE ln1-ln2

This statement allows the text lines from and including any line numbered IS to and including any line numbered ln2 to be deleted during program execution. All variables are retained, excepting that DEFFN variables for DEFFN statements in the delete range are cleared. The string area size is not changed. Any string variable whose current string was actually in the deleted text area has that string moved to the string area. CMD”F”,DELETE must not be executed as a direct statement, must not be contained in a DEFFN statement, a subroutine or a FOR-NEXT loop has a POPS function is implicitly performed), must be the last statement on its text line and must be followed by the text line where execution will continue after the delete. Example:

100 CMD”F”,DELETE 10500-15000

110 X=1 execution continues here after the DELETE is completed

7.19. CMD”F=SWAP”

Swapping of variable contents:

CMD”F=SWAP”,vn1,vn2

This function swaps the value of variable vnl with that of variable vn2. Both variables must be of the same type, i.e., both strings, both single precision floating point, etc. Example:

CMD”F=SWAP”,A$,B$

7.20. CMD”F=SS”

BASIC single stepping:

CMD”F=SS” turn on single stepping

CMD”F=SS”,ln1 single stepping starts at line ln1.

CMD”F=SS”,N turn off single stepping.

The BASIC programmer may now single step through program execution. Using either format 1 or 2 above sets BASIC into single step mode, though for format 2, actual single stepping does not start until text line ln1 is the next line to be executed. A single BASIC text line is executed for each step, and between steps the line number for the next line to be executed is displayed in ‘@nnnnn’ format in the display upper right corner to indicate that BASIC is waiting for the operator to respond. Responding ENTER causes line nnnnn to be executed and then BASIC waits for user response again. Responding BREAK causes execution to be broken in the normal manner though it should be noted that the line number the BREAK shows is for the line just executed or being executed while the ‘@nnnnn’ display is for the next line to be executed. If the user does not change text during BREAK, the program may be continued via CONT; in this case, the ‘@nnnnn’ display will immediately reappear without execution of a line. Pressing ENTER will then execute the line. While in BREAK, the operator may turn single stepping on or off as desired without affecting the ability to CONT. If the BREAK occurs before RUN or LOAD,R executes one text line, CONT will not work.

Single stepping or the scheduling of the single stepping to start when a particular text line is encountered remains in effect until either CMD”F=SS”,N is executed to turn it off or until a format 2 type stepping command is executed, wherein stepping goes off until the specified line is encountered. The execution of RUN, LOAD, NEW, etc. does affect single stepping state.

7.21. CMD”O”

The main memory BASIC array sort has 2 formats:

CMD”0″,n,av1[,av2,....1 (direct sort)

CMD"0",n,*iav1,av2[,av3,...] (indirect sort)

In explaining this sort, the term REN is used and is defined to mean a Relative Element Number identifying an array element. The elements within any BASIC array, regardless of dimension, are integer numbered from 0 up. If an array has only one dimension, then an element’s REN is simply the value of its subscript and if you use only single dimensioned arrays, you can ignore the rest of this paragraph. However, if you use multi-dimensional arrays, then you should know which method to use to increment array subscript values in order to extract elements in the sorted order. CMD”O” does not care what dimension the arrays have; it simply counts off the array elements in the order BASIC stores them in main memory. You, the programmer, do care as you must use subscripts in order to access the array elements. For multi-dimensioned arrays, the rule for computing the REN is complex and can best be illustrated by a three dimension array example using two statements:

	DIM A(R1,R2,R3)
	Y = A(X1,X2,X3)

where the REN of this element is computed as X1+X2*(R1+1)+X3*(R1+1)*(R2+1). If the array had only two dimensions, then the REN would be X1+X2*(R1+1), and, of course, if the array had only one dimension, the REN would simply be X1.

If the CMD”O” statement specifies more than one array, excluding iav1, then the RENs for the first sort item in each array, excluding iav1, must be equal.

The sorting order used has one level for each array specified, excluding the iav1 array, with highest to lowest level in the order, left to right, of the array variables in the CMD statement. Within each level, the normal sort order is ascending ASCII (actually hexadecimal) numeric value for character string arrays and most negative to most positive value for numeric arrays. However, if the array variable in the CMD statement is prefixed with a minus sign (example: -A#(0) ), then the order of sort within that level is descending ASCII (actually hexadecimal) numeric value for character string arrays and most positive to most negative value for numeric arrays. A null compare string character is considered to have a numeric value less than

Normally in character compares, the entire string is used in the compare. However, if the array variable in the CMD statement is suffixed with a field of the form (x,y) (Example: A$(1)(5,4) ), then the compare starts with the xth character of the string and compares using only y characters.

n is the number of elements in each of the arrays participating in the sort. Only n elements from each array participate in the sort. Elements of an array below or above the n elements specified do not participate. If n is a zero value, then for the sort, n is set to the number of elements in first array specified from and including the element specified through and including the last element of the array.

If the number of elements in any array from and including the specified element to and including the array’s last element is less than n, FC error is declared.

A maximum of 9 arrays may be specified. All array variable subscripts, except for the indirect array if specified, must evaluate to the same REN value.

Format 1 is a direct sort meaning that the elements of all 1 to 9 arrays are moved around to conform to the desired sort order.

av1 must be specified; av2 and up are optional.

The resulting order of the n elements in each array is the same for each array (i.e., the arrays are not sorted independently). Thus, if the jth element of array 1 is sorted into the kth element slot, then for each of the other arrays, if any, the jth element is also placed into the kth element slot.

Format 1 is compatible with TRSDOS Model III BASIC CMD”O” if and only if only one array variable is specified, it is for a string array and n is an integer variable.

Format 2 is an indirect sort. In this sort, only the n elements of array iav1 are altered; the other arrays are not changed in any way. The intent of format 2 is to allow a sorted sequence to be determined without actually changing the arrays supplying the sort values. A user may have a group of data records spread across a number of arrays such that a record consists of one element from each array, with the REN of each of those elements making up the record equaling the record number. By using format 2 with the indirect array, the user may effectively sort the records using a subset of the items as the sort criteria and without actually rearranging the order of the records, thus leaving them in record number order.

Format 2, as opposed to format 1, is indicated by specifying the iav1 array variable, prefixed by an * .

iav1 must be an integer array variable.

av2 must be specified; av3 and up are optional.

The n consecutive elements starting at iav1 are initialized with the RENs corresponding to the n consecutive elements of array av2 (which also correspond to the RENs for the other arrays, if any).

During sorting only array iav1 is altered; , arrays av2 and up are not altered.

Upon completion, the n elements of array iav1 are in the desired sorted order such that by using successive values out of array iav1 as subscripts, the user may access elements from any of the other arrays (that are single dimensioned) in that sorted order. Accessing multi-dimensioned arrays is more complex and is left as an exercise for the more advanced user.

Example program using a number of sorts:

10 DIM NM$(200),AM!(100),LN$(l00),IX%(100),ZC!(50),L$(50)

30 X=150

40 CMD”O”,X,NM$(0)

60 CMD”O”,X,-NM$(25)

70 CMD”O”,0,-AM!(1),LN$(1)(5,3)

80 CMD”O”,100,*IX%(0),ZC!(1),L$(1)

At line 40 the first 150 elements of array NM$ (elements NM$(0) to NM$(149) ) are sorted in ascending order. If any of the strings are null, they will appear first in the resulting array. The last 51 elements of array NM$ (elements NM$(150) to NM$(200) ) do not participate in the sort and are left unchanged.

At line 60 elements NM$(25) through NM$(174) are sorted into descending order, with null strings, if any, appearing as the end elements of those 150 elements. The first 25 and the last 26 elements of the array do not participate in the sort.

At line 70 the AM! and LN$ arrays are both sorted, both in the same order which is first by descending order of AM! array values and then, where AM! array values are equal, by ascending order of LN$ array values where only the 5th, 6th and 7th characters of the LN$ array elements participate in the sort determination. If a LN$ array element has less than 5 characters, it is considered a null for sort determination purposes. AM!(0) and LN$(0) do not participate in the sort. Since the number of elements to be sorted was specified as 0, the number of elements to be sorted was taken as 100, the number of elements in the AM! array from and including the AM(1) element to and including the last element of the array.

Line 80 contains an indirect sort. In this sort, the first 100 IX% array elements are initialized sequentially with REM numbers from 1 to 100 with IX%(a) = 1 and IX%(99) = 100. These RENs are used as subscripts to index into the ZC! and L$ arrays. The sort is in ascending order, first by ZC! array values and then, where the ZC1 array values are equal, by L$ array values. None of the elements of the LC1 and L$ arrays are changed in any way. Instead of moving the ZC! and L$ array elements, only the corresponding REM in the IX% array is moved. Upon completion of the sort, the REN in IX%(O) can be used as a subscript to index the first-in-sorted-order element from each the ZC! and L$ arrays, and the REN in IX%(99) can be used to index the last-in-sorted-order element from each the ZC! and L$ arrays. Lastly, remember that elements IX%(100), ZC!(0) and L$(0) did not participate in the sort in any way.

7.22. RENEW

Reinstate a program deleted by the command NEW.

RENEW

The BASIC direct command RENEW reinstates the BASIC program text ostensibly deleted by a just given NEW command. All that RENEW does is set the first byte of the text area non-zero, reestablishes the text forward queue pointers and performs CLEAR. The previous program should thus be reinstated in the text area, available for editing and executing. However, if at least one text line was created or loaded since NEW, then the previous text is not reinstated. Furthermore, if, during this BASIC invocation, the text area never contained any text, RENEW will never the less assume that there is text in the text area and attempt to reinstate it with very disastrous affects to BASIC.

6.1. SUPERZAP

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,dd	The 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,dd	The 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.
	F	The 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,dd	This 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. SUPERZAP enters modify mode and positions the cursor to the first hex digit of relative byte xx (value 00H – FFH) of the current page or sector.
	EXIT	End 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.
	ZTxx	This sequence is displayed vertically in display column 7 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,jk	This 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.
	Q	For sector operations only. Modify mode is terminated, any changes in the buffer are discarded, and SUPERZAP returns to display mode.
	ENTER	For 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.

6.2. DISASSEM

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 EDTASM source 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, column 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. Column 2 indicates which bytes of the instruction have been referenced. If blank and column 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 EDTASM type 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.

6.3. LMOFFSET

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.

6.4. DIRCHECK

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.

6.5. EDTASM Disk Oriented Editor/Assembler

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!!!!

6.6. CHAINBLD

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.

6.7. ASPOOL

	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.

Comments Off [link] [TB]

Comments are closed.

[Ira Goldklang’s TRS-80 Revived Site is proudly powered by WordPress.]

Ira Goldklang's TRS-80 Revived Site

NEWDOS/80 v2.0 Reference – Disk Basic and Included Programs

Search The Site

Translator


	Site Navigation


	More Site Navigation