NEWDOS/80 v2.0 Reference - Chapter 7-END

Chapters

Library Commands

Supplied Programs

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

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 2050, 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.
							
						

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

4. 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.
5. CMD"E" Displays the DOS error messaged associated the latest DOS error encountered by BASIC.
6. 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.

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"O",n,av1[,av2,....1 (direct sort)
2. CMD"O",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.

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.

This chapter deals with the substantial enhancements and some differences in the NEWDOS/80's BASIC'S file handling over that offered by NEWDOS/21, TRSDOS 2.3 for the Model I and TRSDOS 1.3 for the Model III. The statements made in section 7.1 apply to this chapter as well.

These I/O enhancements are more difficult to understand than they are to use, something like electricity which few understand and everybody uses. In the long run, the enhancements will make I/O programming easier, but the user must remember that since TRSDOS does not have these enhancements, your programs will no longer run on TRSDOS.

In NEWDOS/80 version 1, appendix A of the documentation and an executable, heavily documented BASIC program named SAMPLE01/BAS were included as examples and non-specification discussions of these I/O enhancements. In version 2, SAMPLE01/BAS has been dropped from the diskette and Appendix B added containing 18 example programs on marked and fixed item file usage.

Chapter 8 is intended as the specifications for these enhancements; appendices A and B contain supplementary discussion and examples. If there is a conflict between chapter 8 and appendices A and B, chapter 8 governs.

Many terms used in this chapter are defined in the glossary in chapter 10 which the user will need to refer to. The reader should read through this chapter and appendices A and B at least twice before bogging down trying to understand any particular statement.

To the previously existing DISK BASIC file types, sequential which will be called print/input, and random which will be called field item, two other file types have been added: marked item, which has three subtypes MI, MU and MF, and fixed item, which has two subtypes FI and FF.

Print/input (sequential) disk files and field item (random) disk files are well specified for the Model I in the TRSDOS manual, chapter 7 and for the Model III in the TRSDOS manual, part III. The user is expected to have studied the appropriate section before proceeding further with this chapter of the NEWDOS/80 documentation. If necessary, run some test programs to gain proficiency.

A field item file (known in TRSDOS as a random file) has all of its records the same length. This length may be from 1 to 256 bytes. If the record length is other than 256, the BASIC initialization sequence (see section 7.3) must specify the number of fileareas to be allocated and that number must be suffixed with the character V. Example:

BASIC,3V

will cause BASIC to allocate three fileareas with two buffers each, the first to be used in conjunction with the FIELD statement and the second to serve as a full sector buffer. Remember, this special V suffix Is to be used only if the intention is to use a field item file (TRSDOS random) with a record length less than 256; otherwise the extra 256 bytes allocated to each filearea is wasted. The open statement used where the record length is less than 255 is:

OPEN "R",fan,filespec1,lrec1

where lrec1 is the logical record length and has a value 1 - 256.

The essential differences between the four file types are as follows:

Print/input files can only be used sequentially; field item, fixed item and marked item files can all be used either sequentially or randomly. Print/input files are stored in all ASCII character format, converting all numeric data from binary bits to decimal characters. Field item, fixed item and marked item files all store numeric data in the binary forms, thus usually saving disk space and data conversion time.

Print/input files are written to using the PRINT statement which is cumbersome to use because of the need to use the 5 character sequence ;","; to separate two string items. Field item, fixed item and marked item files are written to using the PUT statement with implied separation of file items taken care of by the FIELD statement for field item files, by the implicit or explicit item lengths specified in the IGEL for fixed item files and by the item marker for marked item files.

Print/input files are read using the INPUT statement while field item, fixed item and marked item files use the GET statement.

Field item files require that data be moved into the record buffer before execution of the PUT statement. This is done via the RSET or LSET function and in the case of numeric values, also with MKD,MKI,MKI or MKS$ function. This explicit conversion is not needed for print/input, fixed item and marked item files.

Field item files require that numeric data input from the file be converted from string representation to numeric via the CVD, CVI or CVS function before it is used. This is not needed for print/input, fixed item and marked item files.

Print/input files allow a record length of any size. Field item files allow a maximum record length of 256. Fixed item and marked item allow a maximum record length of 4095 bytes.

Print/input file processing transmits strings to the file without change, but truncates leading spaces from string items when inputted from the file. Strings in field item files are padded on either the left or the right with spaces as necessary during the associated LSET or RSET. Strings in fixed item files are padded on the right with spaces as necessary to fill out the item to its specified length or are truncated on the right if the actual string length exceeds the length allowed the file item. Strings in marked item files are not padded, though the string may be truncated on the right if it exceeds the maximum characters allowed ic that item. Except for this truncation, which must be specified by the programmer, marked item file processing is the only one of the 4 that transmits strings completely unchanged from what they were in the corresponding BASIC variable.

GET and PUT statements execute in two distinct phases in the following order:

1. File positioning phase. The position within the file is set according to the file position parameter, the second parameter, of the GET or PUT statement.

2. Data transfer phase. The data is transferred from main memory to the file (PUT statement) or from the file to main memory (GET statement).

Before proceeding, it is necessary to define three terms used within GET and PUT statements, one that existed in a more limited form in field item file GET and PUT statements and two that are new.

8.4.1 fp File position

For each GET or PUT operation (see sections 8.8 and 8.9), the file is initially positioned according to the fp specification. fp is one of the following forms:

8.4.1.1. null If REMRA is valid and file record segmented, the filearea is advanced to the next record; otherwise fp = null performs as fp = *. Example:

PUT 1,,1000

8.4.1.2. * The filearea position is unchanged. fp = * cannot be used to advance from one record to the next for a record segmented file. Example:

GET 1,*,1000

8.4.1.3. # The filearea is repositioned to REMRA (see section 8.10). This allows the previously processed record to be processed again. Error if REMRA currently invalid. Example:

PUT i,#,1000

8.4.1.4. $ The filearea is repositioned to REMBA (see section 8.10). This allows a return to the positioning of the previous GET/PUT with fp = null, *, #, $, TO, or !rba. Error if REMBA currently invalid. Example:

GET 1,$,1000

8.4.1.5. % See section 8.11 for psuedo FIELD statement discussion.

8.4.1.6. & See section 8.9.6 for PUT, fan,&' discussion.

8.4.1.7. && See section 8.9.7 for PUT fan,&&

8.4.1.8. !rba rba is an expression evaluating to a RBA equaling the desired relative byte position within the file, range 0 to 16,777,215. GET or PUT data transfer starts at the specified location in the file. If the file is record segmented, !rba is assumed to specify a record start position. Example:

GET 1,!1357,1000

********* Use of irba is extremely powerful and when improperly used, quite disastrous!!!!!!!

********* the expression for fp cannot contain a function, such as LOC, that refers to a filearea.

8.4.1.9. !% Same concept as !rba except the current EOF value is used as the RBA. Example:

GET 1,!%,1000

8.4.1.10. !$rba : Position the file to relative file location rba. No data transfer is done. See GET discussion, section 8.8.6. Example:

GET 1,!$1354

8.4.1.11. I$% : Same concept as !$rba except the current file EOF value is used as the RBA. Example:

GET 1,!$%

8.4.1.12. !#rba : Set the expression rba as the new EOF value. See PUT discussion, section 8.9.9. Example:

PUT 1,!#1354

8.4.1.13. rn : An expression that evaluates to an integer in the range 1 - 32767 representing the target record's number within the file. The filearea is positioned to the start of the record's first item. The filearea must be open with m = I, R or D and with ft, if specified, = FF or MF. Example:

GET 1,30

8.4.2. IGEL - Item Group Expression List

A list of expressions corresponding to a group of file items. An IGEL is a series, terminated by a semicolon, of one or more expressions, separated by commas, corresponding to successive file items, starting at the current file position which was established by the GET or PUTs file positioning parameter. If, while searching for a separating comma, the terminating semicolon or the start of an expression, a remark or EOL is encountered, the search goes on to the next BASIC statement. The purpose of an IGEL is to serve as the link between a group of file items and a group of BASIC variables or expressions during the execution of a GET or PUT statement for marked or fixed item file processing- Examples of IGELs (coded in BASIC) are:

1. (30)LN$,(15)FN$,AM!,DT#(X);

2. "3", AN%, NM$;

3. (32)A$(X,Y), B%(2+X), C!, E$, '1st line
K#,FS$;

If an error is encountered while processing an IGEL, the error line number will refer to the line containing the associated GET/PUT statement rather than the actual error line within the IGEL.

8.4.3. IGEL expression

1. Contains zero or more items.
2. The type and length of each item is determined by the GET's or PUT's associated IGEL, and is not determinable from the file itself. This is a basic difference between fixed item files and marked item files.
3. A file may be subdivided into records all of the same length.
4. Maximum length of records is 4095 bytes.
5. The number and characteristics of items of a record is dependent solely upon record length and the IGEL(s) used to GET or PUT the record.
6. An I/O link to and/or from a fixed item file is created by BASIC statement OPEN with ft = FI or FF.
7. Via the GET statement, the contents of fixed item file items are moved into the BASIC variables specified by the IGEL.
8. Via the PUT statement, fixed item file items are created or replaced from the BASIC variables specified in the IGEL.
9. BASIC statement CLOSE terminates an I/O link between the program and a fixed item file.
10. No disk space is skipped between successive items of a file or between the end of one record and the beginning of the next.
11. When an FF file record is created, any unused space at the end of the record is filled with zero bytes.

1. Contains zero or more items.

2. A marked item file item always starts with a control (or marker) byte followed by zero or more additional control bytes followed by zero or more data bytes.

3. Marked file items have the following formats, depending upon the hexadecimal value of the 1st control (or marker) byte.

1. 80-FF 0-127 byte binary string follows.

2. 70 SOR (start-of-record). Each record of a MU file (marked item file segmented into records not all of the same length) starts with this item.

3. 00 Fill item. Used as necessary to fill out MF or MU file records.

4. 71 Next byte contains the count (0-255) of binary string bytes following. This is the only situation (for now) where a second marker byte is used.

5. 72 Next two bytes are a two's complement binary integer. This is BASIC'S format.

6. 73 Next four bytes are a binary floating point number in BASIC's format of the form:

1. Three bytes of normalized absolute value mantissa of the form mmmmm where mmmmm is expressed in these bytes in ascending order of magnitude:

1. Inter-byte, left to right.

2. Intra-byte, right to left. Excepting that the highest ordered mantissa's bit's position, since it's mantissa value is always = 1, is used instead to contain the mantissa sign, 0 = + and 1 = -.

2. The 4th byte contains the base two exponent, biased 128, except if the byte = 0, then the floating point number = 0 regard less of the contents of the other bytes.

7. 74 Next 8 bytes contain a binary floating point number of the same format as for item type '73' excepting that the 1st 7 bytes are the mantissa and the exponent is in the 8th byte. This is BASIC's double precision floating point format.

4. A file may be subdivided into records, either all of the same length (MF file) or of varying lengths (MU file).

5. Maximum length of a file record is 4095 bytes. This includes all record control, item control and data bytes.

6. If the file is divided into records not all of the same length (a MU file), then each record of the file starts with the SOR item automatically supplied by BASIC.

7. Successive records in the file may contain differing numbers of items. This will occur where the programmer has multiple record types within the file. For files with fixed length records, care must be taken to avoid record overflow.

8. Relatively positioned items within records of the file may differ as to type from one record to another. This will occur where the programmer has multiple record types within the file.

9. An I/O link to and/or from a marked item file is created by the BASIC statement OPEN with the ft parameter = MI, MU or MF.

10. Via the GET statement, the contents of marked item file items are moved into the BASIC variables specified in the IGEL.

11. Via the PUT statement, marked item file items are created from BASIC variables and/or BASIC expressions specified in the IGEL.

12. BASIC statement CLOSE terminates an I/O link between the program and a marked-item file.

13. No disk space is skipped between successive items or records of a marked item file. However, SOB. and fill items are inserted as necessary.

1. OPEN m,fan,filespec
2. OPEN m,fan,filespec,len
3. OPEN m,fan,filespec,ft
4. OPEN m,fan,filespec,ft,len

where:

8.7.1. See glossary for fan and filespec definitions. Examples of the four formats:

OPEN "I",1,"XXX/DAT:!"

OPEN "R",2,"XXX/DAT",128

OPEN "O",1,"XXX/DAT:0","MU"

OPEN "D",3,"XXX/DAT","MF",71

8.7.2 Format 1 above is used for print/input and field item files. Format 2 is used for field item files. Format 3 is used for FI, MI and MU files. Format 4 is used for MU, MF and FF files.

8.7.3. m specifies the operational mode for the filearea and is an expression evaluating to a string equal to one of the following:

1. I - The filearea is open to the file for input operations only (INPUT if ft not specified - GET if ft specified). The filearea is positioned to the start of the file.

2. 0 - If the file does not exist, it is created. The filearea is opened to the file for output operations only (PRINT if ft not specified - PUT if ft specified). EOF is set = 0, and the filearea is positioned at EOF.

3. E - Same as "0" except EOF is not changed. This allows addition to an existing sequential file.

4. R - If the file does not exist, it is created. The filearea is opened to the file for GET and/or PUT operations. EOF is not changed, file is positioned as for I. If a subsequent PUT specifies a record at or beyond EOF, the file is automatically extended to include that record.

5. D - Same as R except that the file must already exist and a PUT for a record at or beyond EOF is treated as an error condition.

8.7.4. ft Specifies the file type and is an expression evaluating to a string equal to one of the following:

1. FI - A fixed item file not record segmented. len must not be specified.

2. FF - A fixed item file of fixed length records. len must be specified.

3. MI - A marked item file not segmented into records. len must not be specified. Items within a MI file cannot be updated.

4. MU - A marked item file segmented into records of varying lengths, where the length is determined by searching for either EOF or the next record's SOR item. len is optional and if specified is used as a maximum allowable length for the MU file's records. A MU file record may be updated provided the record length is not increased beyond its original value. If the record is shortened, it is filled out with fill items.

5. MF - A marked item file segmented into fixed length records. len must be specified.

8.7.5. If ft is specified, the following apply:

1. If a GET statement is to actually transfer data from the file to BASIC variables, then the GET statement must specify either IGEL or IGELSN.

2. If a PUT statement is to actually transfer data from BASIC variables or expressions, then the put statement must specify either IGEL or IGELSN.

3. BASIC statement FIELD must not be used.

4. The program must not alter information within the filearea's I/O buffer, and must not rely upon values in that buffer or in the lrec1, NEXT or EOF fields of the FCB.

8.7.6. If ft is not specified and m = R or D, the following apply:

1. The file is a field item (random) file with specifications the same as for Model I TRSDOS 2.3 (Model III TRSDOS 1.3) except as otherwise noted.

2. FIELD statements must be used for proper overlay of BASIC variables into the filearea's buffer. FIELD can process 256 byte records though any one string defined therein is limited in length to 255 characters. The number of bytes defined by a FIELD statement is normally equal to len, should not exceed len and must not exceed 256.

3. GET/PUT statements must not specify either IGEL or IGELSN.

4. If len is not specified, len is assumed equal to 256.

5. len must be a value from 1 to 256. If len is less than 256, then BASIC must have been initialized explicitly specifying the filearea count suffixed with the character V (see section 7.3).

8.7.7. len - An expression evaluating to an integer between 1 and 256 for field item files and between 1 and 4095 for fixed item and marked item files. For field item, FF or MF files, len is the standard length for records of the file. For MU files, len is the maximum length allowed for records of the file. Currently, the file's FPDE does not carry the correct len (lrec1) value; so the len value, explicit or implied, supplied at OPEN is always used. Checks on len are done during GET and PUT. For MF and MU files, the programmer must allow for the following extra bytes in the len calculations:

1. 1 byte for each item (primary item control byte)

2. 1 byte for each string actually containing more than 127 chars.

For MU files, the programmer must allow for the SOR item byte at each record's start.

The number of bytes assigned to a marked file item equals the number of marker (or control) bytes (1 or 2) plus the number of bytes used by BASIC to contain the string or the numeric:

1. Strings: one or two marker bytes plus the actual string length, allowing for truncation due to expression prefix. The second marker byte is used only if the string length is greater than 127 bytes.

2. Integers: 1 marker byte plus 2 bytes.

3. Single precision floating point: 1 marker byte plus 4 bytes.

4. Double precision floating point: 1 marker byte plus 8 bytes.

For fixed item files, the number of bytes assigned to each item is determined from the IGEL as:

1. For strings, for (len)$ and for (len)#, the number specified by the expression prefix.

2. Integers: 2 bytes.

3. Single precision floating point: 4 bytes.

4. Double precision floating point: 8 bytes.

8.7.8. If the EOF in the FCB is modified by OPEN, a subsequent CLOSE or PUT,fan,&& statement will update the new EOF into the FPDE even though no PRINT or PUT statement was executed.

GET fan (fp is null) GET fan,fp GET fan,fp,IGELSN GET fan,fp,,IGEL

							
where:
							
8.8.1. fan and IGELSN are defined in the glossary. fp is defined in section 8.4.1 and IGEL in section 8.4.2. Examples of the 4 formats above are:
							
GET 1
							
GET 1,30
							
GET 1,!X,1000
							
GET 1,,,X%,Y1,Z#,(20)A$;
							
8.8.2. On successful completion of the GET statement, the filearea is left positioned at:
							
1. For marked item file ops, the next item of file.
							
2. For fixed item file ops, the next byte of the file.
							
3. For field item file ops, the next record of the file.
							
8.8.3. If EOR or EOF encountered:
							
1. For field item file ops, the filearea buffer is set to binary zeroes; thus giving binary zero value to all data subsequently referenced. No error occurs.
							
2. For marked item and fixed item file ops, an error occurs.
							
8.8.4. If an error is encountered during GET processing, the filearea control data is reset to the state existing prior to the GET statement. The resulting contents of the variables named in the IGEL or FIELD are in determinant. After error correction, the statement may be executed again.
							
8.8.5. If the GET statement specifies IGEL or IGELSN, then successive file items are processed into successively named variables of the IGEL. For marked file ops:
							
1. If an IGEL expression is null, the corresponding file item is bypassed.
							
2. An IGEL expression prefix can be used to limit the number of characters for the string variable. If the file item has less characters, the string length is set to the lesser value. If the file item has more characters, the excess characters on the right are bypassed and are not passed to the variable.
							
3. As fill items are encountered, they are bypassed.
							
4. Type-mismatch (TM) error occurs if the named variable and tie file item are type incompatible.
							
5. For a record segmented file, a GET for the first item(s) may be followed by a PUT for the rest of the item(s).
							
6. For a record segmented file, record overflow error occurs if GET finds insufficient items in the record.
							
7. Except for the limiting effect of the expression prefix, strings are passed from the file to the variable as is. There is no leading blank suppression.
							
For fixed item file ops:
							
1. For each named string variable, the number of characters specified in the expression prefix is transferred from the file to the string area.
							
2. For record segmented files, 'RECORD OVERFLOW' error occurs if GET finds insufficient bytes in the record.
							
3. Gets and PUTs for successive data may follow one another at will providing:
							
1. The user keeps good track of the current position within the record.
							
2. Record boundaries are observed for a record segmented file. For marked item and fixed item files:
							
The input of a record's items may be spread across two or more GETs.
							
8.8.6. The GET statement of the forms:
							
GET fan,!$rba GET fan,!$% allows the programmer to position the file for the next GET, INPUT, PUT or PRINT statement for that file area. No data transfer is done by this GET statement. !$% means the current value of EOF is to be used as the RBA value. Statements of this form mark REMRA and REMBA invalid. Examples:
							
GET 1,!$2550 positions the file to RBA 2550
							
GET 1,!$X positions the file to the RBA value in X
							
GET 2,!$% positions the file to EOF
						

1. PUT fan (fp = null)

2. PUT fan,fp

3. PUT fan,fp,IGELSN

4. PUT fan,fp,,IGEL

where:

8.9.1. fan and IGELSN are defined in the glossary, fp is defined in section 8.4.1 and IGEL in section 8.4.2. Example codlings of these 4 formats are:

PUT 2

PUT 1,X

PUT 3,,1000

PUT 1,RN!,,(20)A$,B%,C!,D#;

8.9.2. On successful completion of the PUT statement, the filearea is left positioned as done for GET.

8.9.3. If an error is encountered during PUT processing, the filearea control data is reset to the state existing prior to the PUT statement. The resulting data in the file is in determinant, and will probably cause errors to occur upon a subsequent GET. This should be a problem only when updating existing records, and if possible a subsequent PUT for that record should be issued after the error condition has been corrected. To reduce the occasions of file damage, when the file is opened m = R or D, the IGEL is processed once in it's entirety to catch non-1/0 errors and then again to do the actual file update.

8.9.4. If PUT specifies IGEL or IGELSN, then the value of successive IGEL expressions are sent to successive items of the file. For marked item file ops:

1. SOR and fill items are inserted into the file automatically if and when necessary.

2. An IGEL expression may be anything legal on the right side of the equation in a let statement, excepting functions referencing a filearea.

3. Except for the limiting effect of the IGEL expression prefix, the resulting string is sent to the file as is.

4. Numeric literals or expressions are sent to the file as the BASIC numeric type they convert to internally in BASIC.

5. For fixed length records and updated variable length records, each PUT statement replaces that portion of the record from the PUT's file positioning through the end of the record, using fill items if and as necessary. ****** CAUTION Any items previously existing in relative position in the record higher than the last item written by the PUT action are lost, as all of the record's disk space from the last item of the PUT to the end of record now contain fill items.

6. The maximum theoretical sum of bytes for a record (the sum of bytes used for control, for numeric data and for strings) can exceed len (defined in OPEN, section 8.7) so long as the actual number of bytes used during the record's PUT(s) does not exceed len.

For fixed item file ops:

For each string variable, the number of characters specified in the required expression prefix is transferred from the variable to the file by padding with blanks or truncating on the right done as necessary.

8.9.5. For marked item and fixed item files:

1. The output of a record's items may be spread over two or more PUT statements.

2. Data is moved into the filearea's buffer, but is not actually written to disk until one of the following occurs:

1. The filearea is closed.

2. The buffer is needed to contain data from another part of the file.

3. A 'PUT fan,&' or a 'PUT fan,&&' statement is executed.

3. RECORD OVERFLOW error occurs if the allowable record length is exceeded.

4. See OPEN (section 8.7.7) for discussion of the number of bytes used by numeric file items.

8.9.6. The PUT statement of the form:

PUT fan,&

allows the programmer to force the write of the filearea's buffer to disk if that buffer contains data not yet written to disk. If the buffer has no such data, the statement is ignored. The programmer must remember that actual data writes to disk for marked item, fixed item and field item (where len less than 256) files are not necessarily done at PUT time, under the assumption that more write data may yet appear in the buffer. 'PUT fan,&' forces this pending data out to disk, and should be used whenever any of the following conditions exist:

1. It will be some time before the file area will be used again, but the programmer does not want to issue CLOSE.

2. Proper" interaction with other fileareas depends upon the pending data being on the disk.

3. The data is very important.

The file area's file positioning is not affected by the PUT fan,& function. Example:

PUT 3,&,

8.9.7 The PUT statement of the form:

PUT fan,&&

allows the programmer to force the write into the directory of the EOF currently in the filearea's control data. This special PUT will save the programmer the necessity of doing a LOC(fan)! function to remember the current file positioning, a CLOSE to cause EOF write into the directory, an OPEN to reestablish the link to the file, and a positioning GET or PUT to position the filearea back to where it was. Before actually writing the EOF to the directory, the PUT fan,&& function performs a PUT fan,& function. The filearea's file positioning is not altered by the PUT fan,&& function. Example:

PUT 2,&&

8.9.8. The PUT statement of the forms:

     PUT fan,!RBAPUTfan,!RBAPUTfan,!%

function identical to that for GET (see section 8.8.6).

8.9.9. The PUT statement of the form: FUT fan,!#rba

causes the file's EOF to be set to the value of the expression rba, which must evaluate to a RBA. Nothing else is changed for that filearea. Remember, a CLOSE or a PUT fan,&& statement must be executed to force the write of the new EOF into the file's FPDE. Example:

PUT 2,!#2000

causes the EOF in filearea 2's control data to be set to 2000.

1. REMRA REMembered Record Address.
2. REMBA REMembered Byte Address.

where:

1. The ONLY places where REMRA is used is (1) to position the file when the GET or PUT statement has fp - # (see section 8.4.1.3) and (2) in the LOC (fan)$, LOC(fan)J and LOC(1)# functions (see section 8.12).
2. The ONLY place where REMBA is used is to position the file when the GET or PUT statement has fp = $ (see section 8.4.1.4).
3. Both REMRA and REMBA are in RBA format.
4. Each OPEN statement and each GET or PUT statement with rp = !RBAor!RBAor!% marks both REMRA and REMBA as invalid.
5. Each INPUT and PRINT statement sets REMRA to the file position existing at the start of the statement execution. REMBA is not used for print/ input file ops.
6. Each GET or PUT statement with fp = null, rn, !rba, !% or * (for *, only if REMRA is invalid at statement start or if the file is not record segmented) sets REMRA = to the file positioning resulting from that fp value.
7. Each GET or PUT statement with fp = null, rn, !rba, !% or * sets REMBA = to the file positioning resulting from that fp value.
8. Don't let the concepts of REMRA and REMBA puzzle you too much. As stated above, there are only two places where REMRA is used (when fp = # and for the LOC functions) and only one where REMBA is used (when fp = $). If you never use partial record I/O, then REMRA and REMBA are always the same. The most common use will be in executing a PUT (with fp = #) for the record just read.

For fixed item and marked item files, the FIELD statement is not legal. However, there are times when the programmer may want to set the strings associated with an IGEL to their specified lengths and keep them that way by using LSETs and RSETs. The user could do this by using the STRING$ function. Another way is to use the psuedo FIELD function having the following formats:

1. 1. - GET fan,2,IGELSN
2. 2. - GET fan,%,,IGEL
3. 3. - PUT fan,%,IGELSN
4. 4. - PUT fan,%,,IGEL

where:

1. fan and IGELSN are defined in the glossary and IGEL is defined in section 8.4.2.
2. fan specification is required for text format protocol only. Whether the filearea is open or what it is opened for is not of concern to this psuedo FIELD function; this function is only concerned with the IGEL and does not alter the filearea in any way.
3. The IGEL is processed:

1. Numeric variables are left unchanged.

2. Expressions of the form (len)$ and (len)# are bypassed.

3. String variables in the IGEL must be prefixed.

4. String variables are assigned length = to the IGEL expression prefix and either truncated or padded on the right with blanks as necessary. Aside from the padding or truncation, the string contents are not changed. However, if the string is not currently in the string area, it is moved there. Subsequently, LSET and RSET may be used to move data into these strings.

4. Example:

PUT 2,%,,IX2,(30)A,DP#,(10)B ;

causes string AS and B$ to be made into strings 30 and 10 characters in length respectively, being padded with spaces or truncated on the right as necessary. No data is transferred to the file and file positioning is not changed.

1. LOC(fan) where fan is a file area number, 1 - 15, of a filearea opened for field item, MF or FF file operations. This function returns an integer 1 - 32767 = the number of the previous record GET/PUT for that file area. ' 0 = none or REMRA invalid. Example:

PUT 1,34 -X = LOC(l)

results in X have the value 34.

2. - LOC (fan)$ For record segmented files, this function returns -1 (IF statement true) if the start of the next record (if REMRA valid) or the current file position (if REMRA invalid) is greater than or equal to EOF, and returns 0 (IF statement false) if less than EOF. For non-record segmented files and print/input files, this function returns -1 (IF statement true) if the current file positioning is greater than or equal to EOF, and returns 0 (IF statement false) if less than EOF. LOC (fan)$ differs from function EOF in that EOF tests only for exactly at EOF. Example:

IF LOC(1)$ THEN END

ends the program execution if the next record is located at or beyond the file's EOF.

3. LOC (fan)% Returns an RBA equal to the file's EOF. Example, suppose the file contains 3142 bytes:

X = LOC(1)% will result in X having the value 3142.

4. LOC (fan)! For record segmented files, this function returns a RBA value equal to:

1. If REMRA valid, the location of the file's next record.

2. If REMRA invalid, the current file position.

For non-record segmented files and print/input files, this function returns an RBA equal to the current file position.

Example, if the latest fully or partially processed record for filearea 1 starts at relative file position 1667 and the next record starts at relative file position 1701, then

X = LOC(l)!

will set X equal to 1701.

5. LOC (fan)# Returns an RBA value equal to REMRA. Error if REMRA currently invalid. Example, see above example:

X = LOC(1)#

will set X = 1667.

Use of LOC(fan)! and/or LOC(fan)# allows the programmer to obtain the file position of a group of items (non-record segmented file) or a record (record segmented file), remember it for future use, and then at a future time, reposition the file to that data via either fp = !rba or fp = !$rba. This allows programmers to build index files that index into all types of files for random accessing.

The operation of the DISK BASIC statements PRINT, PUT, INPUT, and GET has been altered such that if an error occurs during statement processing, the filearea control data is left unchanged by that statement. This allows the user/programmer more options when an error occurs. Examples:

1. - The program is outputting to a sequential print/input file. 'DISK FULL' error occurs. EOF is returned to where it was at the statement beginning; the file can then be closed, and if no other files are open on that drive, another diskette can be mounted, a new file opened for the same file area, and then the statement in error executed again to continue processing. Later input processing can then process both files, using EOF on the first to trigger the shift to the 2nd.

2. - The program is outputting to a MU file using two or more PUTs to output a single record. 'DISK FULL' error occurs on the 2nd PUT of the current record. EOF is reset to where it was at the error statement's beginning, not to record's beginning. Before switching to a new file, EOF must be set back to the record's beginning via the following two statements:

X!=LQC(fan)#: PUT fan,!#X!

Then the file area may be closed, a new diskette mounted, the filearea reopened, and processing continued back at the beginning for the record (not to the beginning of the PUT). Since a MU file must always start with an SOR item, if two MU files are used in concatenation, the 1st cannot end with a partial record in anticipation of the next containing the rest of the record.

********* The user/programmer must use extreme caution in swapping diskettes on one drive or in swapping a given diskette to another drive when more than the error filearea is open for the original drive.

Also to be remembered is that though the filearea control data is restored to what it was at the statement beginning, the file data associated with a PUT is in determinant, and the contents of the variables receiving data on a GET is also in determinant.

In order to facilitate error recovery and coding in general, BASIC uses a separate control area to perform the GET, PUT or other filearea related operations, leaving the filearea's control data unchanged until the operation completes without error. In NEWDOS80 there is only one temporary control area; a function using a filearea CANNOT be nested within another function using a file-area, even if both file areas are the same. For example, the two statements given above CANNOT be combined into one as:

PUT fan,!#LOC(fan)#

1. For marked item and fixed item files, the programmer GETs or PUTs an item-group of data at one time. The only limitations on the amount of data transmitted are file size and, if applicable, record size. Logical records can be any length between 1 and 4095 bytes. The programmer should never refer to the filearea buffer(s), as the contents at any time are unpredictable. ******** WARNIHG ******* If the program alters data in the filearea's buffer when a file is opened for anything other than field item operations where FIELD was and is legal, the results are unpredictable and usually disastrous. Extreme caution must be used to avoid the file damaging situations where FIELD statements have been legally used, then that filearea used for I/O where FIELD is not legal but RSET or LSET functions continue to be used for one or more FIELD defined strings for that filearea.
2. The special functions designed for field item file ops, (MKD,MKI,MKI, MKS,CVD,CVI,CVS,LSET,RSET,etc.)workasbefore.However,theuseofMKD,CVD,CVI,C?VS,LSET,RSET,etc.)workasbefore.However,theuseofMKD, MKI$, MKSS, CVD, CVI, and CVS may be dropped for marked item or fixed item file ops as GET and PUT will transmit numeric as well as string data.
3. For GET or PUT statements using either IGEL or IGELSN, the programmer must remember that any errors detected during IGEL processing will be recorded as an error occurring on the line containing the GET/PUT rather than on the actual text line of the IGEL.
4. To facilitate error detection for GET or PUT statements using IGELSN, the GET or PUT should be the only statement on its text line.
5. A file can be updated only if it can be opened R or D. MI and print/input files cannot be updated, though of course they may be added onto. MU file records can be updated provided the new record length does not exceed the original length of the record. The last record of a MU file may be extended without this restriction.
6. Fileareas open for print/input files may have GET or PUT statements executed for them if the fp type is !rba,!rba,!%, !#rba, &, && or % .
7. BASIC functions (i.e., EOF, LOC, LOF, etc.) that use fan cannot exist within an IGEL or within OPEN, GET, PUT, CLOSE, PRINT (to disk) or INPUT (from disk) statements. This is a NEWDOS/80 restriction not existing in TRSDOS and is imposed by the error recovery operations (see section 8.13).
8. For disk files whose records can span two or more disk sectors (files whose record lengths are either not standard or do not divide into 256 evenly), the number of actual disk I/O's is increased up to 200% (as compared with files whose record lengths are standard and do divide into 256 evenly) when a record or item group actually has parts in two or more file sectors. The percent overall increase in disk I/O is approximately (LEN/256)*200 where LEN is the average length of records or item groups processed, and where LEN < 256. No approximation is given for LEN >256.

The following is a list of DOS error messages for NEWDOS/80 Version 2 corresponding to error codes placed in register A on a CALL or JP to 4409H. The codes are listed in both decimal and hexadecimal.

If the error code is not defined, "UNKNOWN ERROR CODE" message will be displayed.

SYS4/SYS is the DOS error message display module.