NEWDOS/80 v2.0 Reference – Chapter 7

Table of Contents

7. DISK BASIC, NON-I/O ENHANCEMENTS

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.

1. 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.
2. BASIC programs may disable the BREAK key via CMD”BREAK,N”, and re-enable it by CMD”BREAK,Y”.
3. 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.
4. 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.
5. 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.
6. 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.

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

1. BASIC
2. BASIC
3. BASIC n
4. BASIC m
5. BASIC cmd
6. BASIC n,m,cmd
7. BASIC m,n,cmd
8. BASIC n,m
9. 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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.

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).

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:

1. 1st character of the input line.
2. Followed by either a period or a decimal digit.
3. The input line does not contain an =.

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

1. DI aaaaa,bbbbb
2. DI .,bbbbb
3. DU aaaaa,bbbbb
4. 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.

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.

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

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:

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.

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:

1. REF* Display full reference list for all line numbers, integers and variables.
2. REF$ Print on the printer a full reference list for all line numbers, integers and variables.
3. 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.
4. 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.
5. REF*nn
6. REF$nn
7. REF*sssss
8. REF$sssss
9. 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).

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.

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.

1. CMD”A” Not implemented; use CMD”S”.
2. 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”
3. 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

to

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”.

1. 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.
2. CMD”E” Displays the DOS error messaged associated the latest DOS error encountered by BASIC.
3. 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.

1. 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”.
2. 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.

1. CMD”L” TRSDOS Model III meaning not implemented in NEWDOS/80; use CMD”LOAD,filespec”. This function is not used on the Model I.
2. CMD”O” Array Sort; see discussion below (section 7.21.) for CMD”O”.
3. 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.
4. 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.
5. 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:

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

2. BASIC exited.

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

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

1. 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.
2. CMD”X” Not used on the Model I by NEWDOS/80. TRSDOS’ Model III meaning is not implemented; use the REF command.
3. CMD”Z” Not used on the Model I by NEWDOS/80. TRSDOS’ Model III meaning is not implemented; use CMD”ROUTE,…”.

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

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.

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

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

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

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$

BASIC single stepping:

1. CMD”F=SS” turn on single stepping
2. CMD”F=SS”,ln1 single stepping starts at line ln1.
3. 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.

The main memory BASIC array sort has 2 formats:

1. CMD”0″,n,av1[,av2,….1 (direct sort)
2. 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.

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.

Navigation

Go to …

Page 6 (Chapter 8-End)

Go back to …

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