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

Page Index

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:

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

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.

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

9. CMD”L” TRSDOS Model III meaning not implemented in NEWDOS/80; use CMD”LOAD,filespec”. This function is not used on the Model I.
10. CMD”O” Array Sort; see discussion below (section 7.21.) for CMD”O”.
11. CMD”P” Not used on the Model I. TRSDOS’ Model III meaning is not implemented in NEWDOS/80; use PEEK(&H37E8) to obtain the 0 – 255 value for the current printer status.
12. CMD”R” TRSDOS’ Model III meaning is not implemented in NEWDOS/80; use CMD”CLOCK,Y”. On the Model I, CMD”R” still reenables the interrupts as before.
13. CMD”S” Exit BASIC and return to DOS READY state. However, if the command is of the form CMD”S=doscmd”, then the following occur:

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.

14. CMD”T” TRSDOS’ Model III meaning is not implemented in NEWDOS/80; use CMD”CLOCK,N”. On the Model I, CMD”T” still disables the interrupts as before.
15. CMD”X” Not used on the Model I by NEWDOS/80. TRSDOS’ Model III meaning is not implemented; use the REF command.
16. CMD”Z” Not used on the Model I by NEWDOS/80. TRSDOS’ Model III meaning is not implemented; use CMD”ROUTE,…”.

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

One of the expressions of an IGEL. For PUT statements, an IGEL expression specifies the value to be assigned to the current file item. For GET statements, an IGEL expression specifies the variable to receive as its value the value of the current file item. An IGEL expression is of one of the following forms:

1. exp

2. (len)exp

3. (len)$ fixed item files only

4. (len)#

5. a null expression

where:

8.4.3.1. exp is the main portion of the IGEL expression. Normally, exp names a BASIC variable, but in the case of PUT to a marked item file, exp can be almost anything legal on the right side of a LET statement. When exp is a named variable, either a scalar or an array, it is STRONGLY recommended, though not required, that the variable name be suffixed with one of the 4 type symbols ($, %, !, or #). For example, we STRONGLY recommend:

A$,B%(X,Y),C!,D#;

instead of

A,B(X,Y),C,D;

This recommendation does not apply to subscript variables (i.e., X and Y in the above example).

8.4.3.2. (len)exp is a prefixed expression with len itself an expression evaluating to an integer 0-255. (len)exp must be used only for IGEL expressions that are strings.

1. For marked item files, len is the maximum number of string characters sent to the file during PUT or received from the file during GET. If the actual number of characters is less, then only the lesser number of characters is transferred. For marked item files, use of the (len)exp format instead of the exp format for string expressions is optional, though for MF files, use of the (len)exp is recommended.

2. For fixed item files, the (len)exp format must be used for string expressions in the IGEL as len specifies the exact number of characters a string file item has or is to have. During PUT statement data transfer, if a variable’s string has less than len characters, the file item (not the variable) is padded on the right with spaces as necessary. If the variable’s string has more than len characters, the excess characters on the right are not transferred to the file item. During GET statement data transfer, a variable’s string receives len characters from the file.

3. Example of IGEL using (len)exp expressions:

(30)LN$,(20)FN$,AN%,DP#,(2)CD$(X);

8.4.3.3. (len)$ This expression is legal for fixed item files only. len indicates the number of file bytes to be bypassed. For a GET the specified number of file bytes are bypassed. For a PUT on an existing record, the specified number of file bytes are bypassed and are not altered. For a PUT for a new record, (len)$ defaults to (len)#. Example, in the following IGEL, the 1st 10 bytes are skip ped, the next 12 transmitted, the next 17 are skipped, and the last 8 are transferred.

(10)$,AN%,(10)ST$,(17)$,DP#;

8.4.3.4. (len)# For fixed item files, for a GET, (len)# operates the same as (len)$ and for a PUT sends len zero bytes to the file. For marked item files, for a GET, (len)# bypasses the current file item and for a PUT, sends to the file a character string of len nulls (hex 00 characters). Example:

(10)#,AN%,(10)ST$,(17)#,DP#;

8.4.3.5. A null expression A null expression can only be used in marked item file GET statement IGELs. A null expression causes by passing of the corresponding file item. For example, the first, second and fourth items are bypassed in the execution of the statement:

GET 1,,,,,X!,,A$;

During the processing of an IGEL, if an error occurs particular to one of the expressions of the IGEL, the error message will be prefixed with the expression’s position within the IGEL. For example, if the 4th IGEL expression is in error, the error message will be prefixed with a 4.

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.

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.

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.

In addition to the standard ROM BASIC LEVEL II error codes, the following DISK BASIC error codes are used:

SYS13/SYS is the module that displays DISK BASIC and ROM BASIC error messages. It is normally not in memory until needed. If an error code is generated for which there is no message, UNPRINTABLE ERROR is displayed.

This chapter contains the definitions of some of the terms used throughout the NEWDOS/80 documentation.

alpha or alpha character

– Used when referring to the set of characters A-Z and a-z.

alphanumeric

Used when referring to the set of characters A-Z, a-z and 0-9.

bit

The smallest accessible unit of main or diskette memory. A bit has a value of either 0 (meaning off) or 1 (meaning on). A group of 4 consecutive bits is known as a hexadecimal (or hex) digit, and a group of 8 consecutive bits is known as a byte. Whenever the documentation refers to a bit within a byte, the convention is bit 7 is the bit on the left and bit 0 is the bit on the right with the order of bits within a byte going left to right, 7 to 0. The concept holds for bits within a hex digit, left to right, 3 to 0.

boot

see reset/power-on.

BOOT/SYS

One of the two control files required on every diskette used with NEWDOS/80. See section 5.1.

buffer

An area of main memory used to hold the contents of a sector read from disk or to hold the new contents of a sector being written to disk. Each open FCB has a 256 byte buffer assigned for this purpose. Byte mode disk I/O, such as is used for print/input, marked item, fixed item, and (if record length less than 256) field item files actually operates to and from the buffer with disk sector reads and writes being done when necessary, and not on each GET or PUT or PRINT or INPUT statement execution.

byte

The smallest addressable unit of main or diskette memory. A byte is composed of 8 bits. When the value of a byte is given, it is usually expressed as two hexadecimal digits. In NEWDOS/80 documentation the words byte and character are used interchangeably even though character can have a more restrictive meaning.

chaining

Used in NEWDOS/80 to refer to the process of bringing keyboard input characters from a disk file known as a chain file. See section 4.3.

character

Used interchangeably with byte, but also used to refer to a byte containing a printable value.

close

In disk I/O, to close a FCB or a filearea means to dissolve the link between a program and a disk file created by the open function.

DEC          Directory Entry Code

A one byte code used to specify a particular FDE and used by DOS to quickly locate that FDE in the directory. When an FCB is open, its 8th byte contains the DEC for the file’s FPDE. Each FXDE contains in its 2nd byte the DEC for the preceding FDE for the same file, and each FPDE or FXDE whose 31st byte = 255 (0FEH) contains in its 32nd byte the DEC of the next FXDE for the file. The format of the 8 bit DEC is:

rrrsssss

where sssss+2 = the relative number within the directory of the sector containing the FDE, and rrr times 32 (20H) equals the relative byte address within the sector of the FDE.

DIR/SYS          see sections 5.1 and 5.6.

One of the two control files required on every diskette used with NEWDOS/80. DIR/SYS contains the directory for a diskette.

directory see sections 5.1 and 5.6.

In DOS, the directory refers to the contents of the file DIR/SYS that must be present on every diskette used by NEWDOS/80. The directory contains the control information specifying all files and the free or allocated state of all space on the diskette. If the directory is damaged or destroyed, the rest of the information on the diskette is usually, but not always, no longer available to the user.

DOS          Disk Operating System

Though many thousands of programmers are quite capable of writing their programs to communicate directly with the diskette, it is almost always preferable to allow another program, or collection of programs, to act as an intermediary between the user program and the disk files the program uses. This intermediary is commonly called a DOS and serves to both structure and vastly simplify a program’s I/O with the files it uses. Usually, as in NEWDOS and TRSDOS, the DOS functions are much more extensive such that the DOS becomes the primary control program in the computer and has available various other functions, other than disk I/O control, that it performs in response to commands, known as DOS commands (specified in chapter 2), or DOS calls (specified in chapter 3). In NEWDOS/80, the DOS operates in the 4000 – 51FFH region of main memory with some of its functions using the 5200 – 6FFFH region and the spooler running out of highest memory.

DOS-CALL or dos-call

Refers to the DOS state entered when a user program calls the DOS routine at 4419H (see sections 3.11 and 4.4) to execute a DOS command or a user program. There can be multi-levels of DOS-CALL state.

DOS command or doscmd

Refers to one of the built-in DOS functions described in chapter 2. DOS commands can be executed by keying in from the keyboard or through calls from the current executing program (see DOS-CALL).

EOF          End of File

Of or pertaining to the end of a file. SOME files have one or more specific EOF bytes that mark the end of a file (assembler source files use lAH, BASIC non-ASCII text uses 3 consecutive bytes of zeroes, etc.); however, most files do not and rely entirely upon the EOF within the FCB or FPDE to indicate where the file ends. If a file is empty, EOF equals 0 and if a file has 1324 bytes, the EOF value expressed as an RBA is 1324. Within a NEWDOS FCB, EOF is a three byte RBA value of the file’s last byte +1. The EOF value stored in a file’s FPDE is not in RBA format. See sections 5.7 (fpde bytes 4, 21 and 22) and 5.9 (FCB 9, 13 and 14).

EOL          End Of Line

Of or pertaining to the end of a line. For input data or a command, this is usually the ENTER character (0DH). For BASIC text, a zero byte ends a line. If the line does not have an explicit EOL character, then EOL means the line’s last character + 1.

EOM

Of or pertaining to the end of a message. The EOM character code is 03. EOM is used to end a message when that message end is not also the end of the line. When encountered, the EOM character is not displayed or printed nor is the display or printer advanced one character.

EOR          End Of Record

Of or pertaining to the end of a record. EOR is also the relative byte address within the file of the record’s last byte + 1.

EOS          End Of Statement

Of or pertaining to the end of a statement. For BASIC text, a colon ends a statement.

extent element

A two byte control element within a FPDE or FXDE specifying a 1 to 32 granule contiguous area of diskette storage assigned to the file. See section 5.7, FPDE 23rd-30th bytes.

fan          file area number

A fan is a BASIC expression evaluating to an integer (range 1 – 15) specifying which filearea is to be used for the current BASIC function.

FCB          File Control Block.

See section 5.9. A data area containing information controlling an I/O link between a program and a diskette file. The link is created by the open function, dissolved by the close function, and used by all other disk I/O functions including GET, PUT, PRINT, INPUT, LOC, etc. The FCB contains the NEXT and EOF fields, the buffer address, security information, record length, etc.

FDE          File Directory Entry. See section 5.6.3.

In NEWDOS, each sector of the directory file DIR/SYS, except for the first two, is divided into eight 32 byte control areas called FDEs. A FDE is either free (available for assignment) or in use as a FPDE or FXDE.

FF file

A BASIC fixed item file segmented into records all of the same length,

FI file

A BASIC fixed item file that is not record segmented.

file or disk file or diskette file

A collection of data on a disk or diskette. A file may contain diskette control information (as do BOOT/SYS and DIR/SYS), a machine language executable program (as do SYS0/SYS, BASIC/CMD and SUPERZAP/CMD), a BASIC program (as does CHAINTST/BAS) or user data (such as mailing lists, payroll, inventory). Control data for all files is contained within the file DIR/SYS (see section 5.6) with each file being assigned one FPDE and zero or more FXDEs. A file must exist entirely on one diskette. Diskette space is allocated to a file as needed in units called granules.

filearea

An area of BASIC’S system storage containing control information, a FCB and a 256 byte buffer. A filearea is used during disk file operations to maintain an I/O link between a file and the BASIC program. This I/O link is established by OPEN, used by PRINT, INPUT, GET, PUT, FIELD, EOF, LOF, LOC, etc., and dissolved by CLOSE. When 2 or more fileareas are open to the same file, each acts in ignorance of the others. A BASIC program may have open at any one time as many as 15 fileareas. The number of file-areas actually available to the BASIC program is specified when BASIC is activated (see section 7.2) with the default being 3.

field item file

This is a name used in NEWDOS/80 for what, in TRSDOS disk BASIC, is called a random file since all three types of files, field item, fixed item and marked item can be used either randomly or sequentially or both. Field item and fixed item files are essentially the same type of file; the main difference is in the type of I/O link, field item or fixed item, used. For field item files, the definition of the file items is done solely via the FIELD statement. Field item files are always segmented into records all of the same length, with that length being from 1 to 256 bytes.

file item

A unit of file storage zero or more bytes in length containing a numeric value or a character string.

filespec

This term is used in NEWDOS/80 to refer to the combination of file name, name extension, password and drive number used to specify a file in a DOS command, BASIC statement or an unopen FCB. Of the four elements, only file name is required. See section 2.1 for full definition of filespec.

fixed item file          See section 8.4.

Fixed item and field item files are essentially the same type of file. The difference lies in the type of link, field item or fixed item, used in the file I/O. For fixed item file processing, the definition of the file items is entirely dependent upon the IGEL used in the GET or PUT statement. There are two types of fixed item files, FI and FF.

format

Aside from many other definitions of the word format, it is also the word used for the process that prepares a raw diskette for use under NEWDOS/80. This process magnetically structures the diskettes into tracks which are at the same time further sub-divided into 256 bytes sectors. Depending on the drive type, the diskette will contain 35, 40, 77 or 00 tracks, and depending upon the drive type and recording density, each track will contain 10, 17, I8 or 26 sectors.

fp          file positioning

See section 8.4.1. fp refers to the second parameter of a GET or PUT statement. fp specifies the file positioning to be done during the file positioning phase that precedes the data transfer phase, if any, of a GET or PUT statement.

FPDE          File Primary Directory Entry

See section 5.7 for FPDE specification. A FPDE is created in the diskette directory whenever a file is created. If a file exists on a diskette, there will always be a FPDE for it in the directory. The FPDE contains the file name, extension, passwords, protection level, EOF, the first 4 extent elements and other information. When a file is killed, the FPDE and any associated FXDEs are dissolved.

FXDE          File Extended Directory Entry

See section 5.8 for FXDE specification. Whenever the number of extent elements needed to account for a file’s diskette space exceeds four, one or more FXDEs are created in the directory to hold the extra extent elements, a maximum of four per FXDE. If a file has FXDEs, they are accessed via the FPDE. As a file’s diskette space requirements change, FXDEs are created or dissolved as necessary, and when a file is killed, all FXDEs associated with that file are dissolved.

GAT          Granule Allocation Table

See section 5.6.1. The GAT is that portion of the directory’s 1st sector (known as the GAT sector) wherein the free or allocated status of each granule is accounted for.

granule

The smallest unit of diskette storage allocatable to or de-allocatable from a file. When a file needs diskette space, one or more granules is allocated. For NEWDOS/80 a granule consists of 5 sectors equaling 1280 bytes.

hash code

Hash code as used in the DOS refers to a one byte encode of a file’s name and extension used during open to rapidly find the file’s FPDE in the directory. Hash codes are stored in the HIT sector, see section 5.6.2.

hexadecimal or hex

A numbering system using 16 digits, rather than 10 used by the decimal system. The digits are 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E and F. The reason for the use of hexadecimal as opposed to decimal is that a hexadecimal digit is an easy way to express the value of 4 consecutive bits, where the following table defines the correspondence between a hexadecimal digit and four binary bits.

Hexadecimal representation of disk, file or main memory locations and contents are widely used in the computer industry. Though some users can get by without learning anything of hexadecimal, we strongly recommend that users learn the rudiments, at least enough to understand the SUPERZAP and DEBUG displays. Throughout NEWDOS/80 and its documentation a hexadecimal numeric value is expressed with a suffixed H character (i.e., 13 = 0DH or 256 = 100H) unless otherwise specified.

HIMEM

Refers (1) to the address of the highest usable main memory location, (2) to the 2 byte main memory area (Model I locations 4049H – 404AH and Model III locations 4411H – 4412H) where the HIMEM value is stored and (3) to the name of a DOS command (see section 2.25). Main memory above HIMEM is either non-existent or is reserved for other uses. All user Z-80 code programs should be coded to observe HIMEM.

HIT          Hash code Index Table

See section 5.6.2. That portion of the directory’s second sector (also known as the HIT sector) that contains the hash codes for all files on the diskette. Instead of searching the entire directory for a file’s FPDE during open, DOS computes the hash code from the file name and extension, looks it up in the HIT sector and then goes directly to the sector containing the FPDE.

I/O          input and/or output

I/O link or I/O path

Actual disk I/O between a disk file and main memory is done via an I/O link (also known as an I/O path) created by open, dissolved by close, and used by GET, PUT, PRINT, INPUT, LOC, EOF, etc. While the link is open, the controlling information for the link is contained in a FCB or filearea (which contains a FCB). Multiple links to the same file can be open at the same time with each link knowing nothing of the others. An I/O link remembers the position in the file where it is operating; thus multiple links can be operating on the same file at the same time. However, be careful as, remember, each I/O link knows nothing of the other’s actions.

IGEL          Item Group Expression List

See section 8.4.2. An IGEL is a list of BASIC expressions corresponding to a group of file items during the execution of a GET or PUT statement used in fixed item or marked item file processing.

IGEL          expression See section 8.2.3.

An IGEL expression (usually but not always a BASIC variable) is that part of an IGEL corresponding to a file item. For each file item processed in a fixed item or marked item file GET or PUT statement, there is a corresponding IGEL expression in the IGEL.

IGELSN          IGEL Sequence Number

The line number (also known as sequence number) of the BASIC text line containing the first or only line of the IGEL to be processed by the current GET or PUT statement. If used, the IGELSN is the 3rd parameter of the GET or PUT statement. An IGELSN is used in a fixed item or marked item GET or PUT statement whenever the GET or PUT statement itself does not contain the IGEL, and this usually occurs when the same IGEL is used by two or more GET and/or PUT statements.

item group

A group of zero or core file items. In BASIC, an item group is the zero or more file items processed by an individual INPUT, PRINT, GET or PUT statement and is most commonly equivalent to a logical record.

len See section 8.7.7 and see LRECL

The parameter in a BASIC OPEN statement that specifies either the standard or the maximum record length.

logical record

A group of meaningful related file it eras. Though file data is physically ordered on the diskettes into sectors, the programmer usually deals with data groupings that are logically related and grouped, rather than physically related and grouped. Thus, when data is read from or written to a file, it is usually done so in logical record units.

LRECL          Logical RECord Length

This is the standard or maximum length in bytes for records of a file. For non-BASIC files LRECL is 0 – 255 (with 0 meaning 256) and is stored in the FPDE’s 4th byte (though never used) and the FCB’s 10th byte. In BASIC, LRECL is equivalent to len (see section 8.7.7).

lump

refers to a division of diskette space as that space is accounted for in the diskette directory. Each of the first 192 bytes in the GAT sector contains either space allocation or lockout information for one lump where, depending on the number of granules per lump, each bit within the byte is either unused or specifies the allocated/free or non-existent/ existent state of one of the lump’s granules. This definition was coined for use with NEWDOS/80 Version 2 to avoid using the words track and cylinder. See sections 5.6.1 and 5.7 (23-30th byte discussion).

marked item file          see section 8.6.

A file in which each file item is identified as to length and type by a prefixed marker byte. A marked item file is distinctly different from a print/input, field item or fixed item file. The three types of marked item file are MI, MU and MF.

MF file

A marked item file that is segmented into records all of the same length.

MI file

A marked item file that is not record segmented.

ms          millisecond

MU file

A marked item file that is segmented into records of differing lengths.

null

The absence of a parameter or expression. When parameters are separated by commas back to back commas(,,) indicate a null.

null character

A character or byte with value = 0.

null string

A string or an expression evaluating to a string zero characters in length.

open

In disk I/O, to open a FCB or a filearea is to establish a link between the program and a disk file, using the FCB or filearea (which contains a FCB) to hold the link’s control data. Though it is quite common to say that a file is opened, it is more correct to say that a FCB or filearea is opened for there is nothing in the disk file indicating open or closed state or the number of links opened to it as more than one FCB or filearea may be open to a given file at the same time. The link established by open remains until dissolved by the close function. It is the link that determines the type of I/O done with a file and where in the file. Thus, if differently specified links are established to the same file to exist concurrently, the same file data can be used but interpreted differently by each of the different links.

partial record I/O

Refers to instances where I/O is done in partial rather than full logical records. In BASIC, GETs and PUTs for marked-item and fixed-item files may operate in this manner though they usually operate in whole record I/O mode.

patch          see zap.

power-on/reset          See reset/power-on

print/input file

A disk file written to by PRINT statements and read by INPUT statements.

record segmented file

A type of file that can be broken down into logical records by BASIC. These file types are field item, FF , MF and MU.

REMBA          REMembered Byte Address

See section 8.10.

REMRA          REMembered Record Address

See section 8.10.

RBA          Relative Byte Address

A method of addressing within a file, record, control block, etc. where addressing starts at 0 rather than 1. The first byte of the unit has RBA = 0. The nth byte in the unit has RBA value = n-1. In NEWDOS, RBA is used to express EOF and NEXT in the FCB; this use of RBAs in the FCB is major difference between NEWDOS and the old versions of TRSDOS. In BASIC, RBA is used in file positioning (see section 8.4.1) where, in fp = !rba, !$rba or !#rba, rba is defined to be a BASIC expression evaluating to a number between 0 and 16,777,215 and represents a relative byte position from the beginning of the file.

reset/power-on          also known as boot.

refers to the automatic computer execution that occurs whenever the computer’s reset button is pressed or when the computer is powered up. In reality, you must. never have diskettes in any drives when you power up the computer. After the power up, put the system diskette in drive 0 and press reset. For the most part, NEWDOS/80 treats a reset after power-on the same as a reset at any other time. There are some differences, however, with the most notably being the date and time settings that occur.

During a reset/power-on, the ROM’s bootstrap routine receives computer control from the hardware reset logic and reads the first sector of the diskette mounted in drive 0 into the DOS system buffer (4200H -42FFH on the model I and 4300H – 43FFH on the model III). That 256 bytes contains NEWDOS’ s bootstrap routine which receives computer control from the ROM and then reads into main memory a fresh copy of NEWDOS/80’s main memory resident module SYS0/SYS. Execution control is then passed to SYS0’s initialization routines in the DOS overlay area. Using the current SYSTEM and PDRIVE specifications, NEWDOS/80 is initialized. When this is completed, either NEWDOS/80 READY is displayed or DOS commences the execution of the AUTO (see section 2.4) specified DOS command.

sector

For NEWDOS/80, diskette data storage is physically done in groups of 256 bytes called sectors. Actual diskette reads and writes are done by whole sectors, usually a single sector at one time.

SOR Start Of Record

Of or pertaining to the start of a record. All records of a MU file start with a SOR item, a 70H byte.

track

The unit of diskette storage a disk drive read/write head passes over during one revolution of the diskette. A diskette is divided magnetically into a number of concentric tracks during format (35 is standard on the model I, 40 on the model III). Format also divides each track magnetically into 256 byte sectors which will subsequently contain data of any and all kinds.

user segmented file

A type of file which cannot be broken down into logical records by BASIC. These file types are FI and MI. If these file types are to be segmented into records, it is done so solely by the programmer without BASIC’s knowledge.

vice

Means ‘instead of or ‘in place of’.

whole record I/O

Whole record I/O is when an entire logical record is read or written during the execution of a single INPUT, PRINT, GET and PUT statement. This is the normal procedure for those statements. See partial record I/O.

zap

To alter data or program executable code without recompilation. See section 11.

As with previous NEWDOS versions, NEWDOS/80 Version 2 will contain errors not presently known, will receive minor enhancements as the months pass, and has incompatibilities with other DOSs including earlier versions of NEWDOS. Where possible and economically feasible, patches (zaps) will be issued to correct the errors, provide the enhancements and, in selected cases, relieve the incompatibilities.

Apparat relies heavily on the NEWDOS/80 users to find and inform Apparat of NEWDOS errors and incompatibilities. Over half of the zaps generated for NEWDOS/80 Version 1 were a direct result of an error properly reported. In some cases, the user had to report the error more than once before Apparat either paid attention or finally found the error. Reported errors may or may not be fixed, depending upon the seriousness, the magnitude and the amount of zap area available in the affected modules. If an error is not to be fixed, Apparat will, in a comment zap, report the error and announce that it will not be fixed.

NEWDOS/80 is a different DOS from TRSDOS, VTOS, LDOS, DOSPLUS and others; therefore many user programs will not operate on NEWDOS/80 without some modification. For any particular program, the best thing is to try that program out with NEWDOS/80; be sure you do not use valued file data in these tests. In the past, Apparat has tried to create and distribute the necessary patches to commonly used, commercially sold programs, but this proved unworkable for a number of reasons.

1. Apparat was not notified by program manufacturers of a pending release of a new program and of its actual incompatibility with NEWDOS/80. The discovery of the incompatibility always came from the users. This is not a criticism, only a statement of fact.
2. Apparat did not and does not have the personnel resources to research each incompatibility problem and to generate the necessary zaps to the non-NEWDOS/80 programs.
3. The mailing of zaps to all registered NEWDOS/80 owners was delayed until a number of zaps were available, a delay usually of months, though Apparat would mail out the latest zaps to individuals on request. It would be much better if the necessary incompatibility zaps were sent out along with the non-NEWDOS/80 program. Apparat, in the past, did not make an effort to send the zaps to the manufacturers to include with their programs, and for this we apologize.

For NEWDOS/80 Version 2, Apparat will still issue compatibility zaps for some application programs, but fundamentally Apparat will rely on the creator and/or distributors of non-NEWDOS/80 programs to produce and distribute the zaps necessary, if any, to run those programs with NEWDOS/80. To assist in this effort, Apparat offers a free copy of NEWDOS/80 to business firms that product: software products to be used on NEWDOS/80, provided these products are advertised in a major publication (NEWDOS/’80 need not be mentioned in the advertisement) .

To reduce confusion, frustration, cost and wasted time, Apparat requires that the following be done:

1. Read and understand the applicable documentation.
2. For errors, assure that language programs using NEWDOS/80 are interfacing correctly. Apparat does not check out programs other than what it creates.
3. Assure that all outstanding mandatory zaps have been applied to your NEWDOS/80 system or user programs.
4. Run the circumstances resulting in the NEWDOS/80 error or incompatibility many times under varying conditions (if possible).
5. Precisely and concisely write up the error circumstances and send, along with applicable diskettes, to: Apparat, Inc.
   4401 S. Tamarac Parkway
   Denver, CO 80237
6. Include your NEWDOS/80 registration number.
7. Include copies of the diskettes (as gifts to Apparat) containing the all the modules involved in the error or incompatibility. Apparat will destroy the diskettes’ contents, including any copies made of them, when done with the error study.
8. DO NOT PHONE Apparat directly.: Phone answering personnel are not technically knowledgeable of NEWDOS.
9. DO NOT INCLUDE product orders or other requests with your error report.

In NEWDOS/80, zaps (patches) are manually applied by using the program SUPERZAP discussed in section 6.1. The user should study section 6.1 to learn how to use SUPERZAP, but if he/she prefers not to do that, enough information will be provided in this chapter to scrape by.

Though SUPERZAP is a somewhat cumbersome method of applying zaps, this method does have the advantage of forcing the users to learn how to use SUPERZAP and gives them confidence in using that program they would otherwise not have acquired. Sooner or later, everybody needs to use SUPERZAP to help repair damaged disk files, and when this emergency arises, the more experience the user has had with SUPERZAP, the better.

NEWDOS/80 zaps are consecutively numbered and are dated with the date the zap was made available. A zap will be either mandatory or optional, and it is either for a NEWDOS/80 module (i.e., one of the files on the NEWDOS/80 master system diskette) or for a non-NEWDOS/80 module. If it is mandatory zap to a NEWDOS/80 module, and your NEWDOS/80 system diskette is dated later than the zap, the zap will usually, but not always, already have been applied to your diskette.

Each zap will have a short explanation of the reason for it. Next will follow one or more zap areas, with each area composed of three parts:

1. – The location on the diskette of the first byte of the area. This location will consist of 3 parameters and will be in the following format.

filespec1.relsector,relbyte

where

1. filespec1 gives the name or name/ext of the file to be zapped.

2. relsector is the relative sector within the file. relsector is in decimal.

3. relbyte is the relative location within the sector of the zap area’s 1st byte. relbyte will be in hexadecimal but will not be suffixed with the character H.

Examples:

DIR/SYS,2,20

EDTASM/CMD,20,F6

YOURFILE,0,88

2. – The old contents of the zap area. Each byte will be printed as two hexadecimal digits, and for readability the bytes will be separated by at least one space. If a hex digit position contains a – , then either Apparat doesn’t care or doesn’t know what exists in that hex digit before it is zapped.

3. – The new contents to be zapped into the area, printed in the same format as for the old contents.

If a zap area covers more than 24 bytes, the format is changed so that both the before and after areas will be aligned to appear as the user will see them on the SUPERZAP display. This makes for easier viewing and zapping.

Many zaps really do not change the first and/or last bytes of the zap area. These bytes were included to help the user synchronize on the proper area, both before and after the zap, and to provide more verification bytes. However, it is not mandatory that the first and last bytes of the zap area be used this way, and they usually won’t be if the current zap area adjoining or overflows the area of another zap or if the zap area starts, ends, or overflows a sector boundary.

1. Make at least one backup copy of the diskette to be changed. NEVER, NEVER, NEVER, NEVER apply a zap without first making a backup copy!!!
2. Execute DOS command SUPERZAP.
3. Mount the diskette containing the file to be zapped.
4. Enter the SUPERZAP function code DFS.
5. Enter the filers filespec, containing (1) the name or name/ext from the zap area location’s 1st parameter (see section 11.4.1.1.) (if the file has been renamed, then use the applicable name/ext), (2) the access password, if required, and (3) the drive number.
6. Enter the zap area location’s 2nd parameter (see section 11.4.1.2) as the relative sector number within the file.
7. The sector will be displayed to the user (see step 14 below). Find the zap area in the display, and verify that the old contents are as they should be. If they are not, then check if the zap you are about to apply is already applied; it may well be. If it is, then skip the current zap area and go on to the next. If it isn’t, then check Apparat.
8. When satisfied with the old contents, type MODxx without ENTER. xx is the zap area location’s 3rd parameter (see section 11.4.1.3.).
9. The cursor should appear over the first hex digit of relative byte xx. If the cursor does not appear, type in MODxx again. If the cursor appears over the wrong digit, check to make sure you are where you think you are. CAUTION!!! When the cursor appears, SUPERZAP is in modify (overwrite) mode; be careful what keys you press. In modify mode, left, right, up and down arrows and the space bar may be used to move the cursor.
10. To alter the hex digit in the cursor position, press the proper 0-9 or A – F key that represents the replacement value. The cursor will automatically advance to the next hex digit.
11. Type in all the new hex digit values.
12. If not satisfied with the changes, press Q to cancel the modification and return to the display.
13. When satisfied with the changes and ready to update them to the diskette, press ENTER. Then press Y, and when instructed, press ENTER again. SUPERZAP will exit modify mode back to display mode.
14. When an sector display mode (no cursor):

1. Press K if you wish to display another sector of the same file. Go to step 6.

2. Press J if you wish to go on to another file. Go to step 5.

3. Press X if you wish to return to the function menu.

4. Go to step 7 if there is another zap area for this same sector.

Apparat requires registration of all NEWDOS/80 owners and will limit distribution of its zaps to registered owners. Please notice that, unlike other registration forms, the NEWDOS/80 registration card does not require the NEWDOS/80 owner to agree to anything; just let us know who you are !

Apparat does not guarantee that zaps will be distributed, as such distribution is a cost to Apparat over and above what the purchaser paid for NEWDOS/80. Apparat reserves the right to institute a charge for the zaps at some future time.

Zaps will be distributed by mail. Zaps will NOT be given over the phone. Distribution of zaps to all registered owners will occur whenever a large number of zaps has been accumulated. However, upon request, the latest zaps will be sent to individual registered owners, but please, if you are not having any trouble with your NEWDOS/80, don’t ask.

When Apparat receives a registration card, the latest copy of the zaps will soon thereafter be mailed to the registered owner. This lets the owner know that Apparat has received the registration card and provides the owner with any zaps generated since either that manual (containing zaps as chapter 13) was made up or that NEWDOS/80 diskette was created.

When you first receive your NEWDOS/80, chapter 13 will contain the zaps out standing at the time your manual was made up. Some of the pages for that chapter may have been inserted in the front of the manual at the last minute; find them and put them in chapter 13.

Next, make some backups of the NEWDOS/80 master diskette.

Now, since your NEWDOS/80 manual may or may not have been made up at the same time as your NEWDOS/80 diskette, you must synchronize the diskette with the zaps, if any, in chapter 13. Most of the mandatory zaps to NEWDOS/80 modules will already have been installed, but you oust still check.

Using SUPERZAP, test if the highest numbered mandatory zap for a NEWDOS/80 module has already been installed. If it has, then you nay assume all lower numbered mandatory zaps for NEWDOS/80 modules have been installed. This is not the case for optional zaps to NEWDOS/80 and any zaps to non-NEWDOS/80 programs. If this highest numbered mandatory NEWDOS/80 module zap has not been applied, then, check the next lower numbered such zap until you reach one that has been installed. Then, from but not including that zap, start applying the higher numbered mandatory NEWDOS/80 module zaps in ascending numeric order. Higher numbered zaps may well zap over an area covered by a lower numbered zap.

Apparat has received many complaints from users who did not realize that some or all of these mandatory zaps were already applied to their diskette. As a general rule, but you must still check, a mandatory NEWDOS/80 module zap is installed on your diskette if your diskette is dated later than the zap.

As well as applying the mandatory NEWDOS/80 module zaps, you must apply the mandatory zaps, if any, to those non-NEWDOS/80 modules you are going to use with” NEWDOS/80. You should also at least read the optional zaps so you know they exist.

Finally, though you will probably never know it, it is possible that your’ NEWDOS/80 diskette will have some mandatory zaps installed not yet listed in your chapter 13. This is not common, but such a thing has occurred. The zap sheets you receive in response to sending in your NEWDOS/80 registration card should cover those unknown but nevertheless already installed zaps.

When you receive a zap mailing from Apparat, you should apply the new mandatory zaps to NEWDOS/80 modules and to those non-NEWDOS/80 modules you are using with NEWDOS/80.- Once again, you. should at least read through the new optional zaps. There is no need to reread the zaps that you already have, as zaps are seldom updated and if. they are, usually a subsequent zap refers to the change.

Remember, your NEWDOS/80 master diskette may already have some of the newer mandatory NEWDOS/80 module zaps applied; so check the highest numbered new zap and work your way down until you come to a zap that has been installed. Then start installing higher numbered zaps in ascending zap number order.

Never apply a higher numbered mandatory NEWDOS/80 module zap before applying all lower numbered mandatory NEWDOS/80 module zaps.

In NEWDOS/80 version 1, due to the large number of zaps, Apparat instituted a NEWDOS/80 original diskette zap update service that is being continued for Version 2. This service does not replace the zaps but is intended for those users who would prefer Apparat to apply the zaps.

The user sends a package to Apparat containing his/her original NEWDOS/80 diskette, $10.00 for service and handling, and a note explaining that the zap update is wanted. Address the package to:

APPARAT, INC.
NEWDOS80 Diskette Update Service
4401 S. Tamarac Parkway
Denver, Co 80237

Do not include any other information or requests in this package. Include in your note your phone number, your NEWDOS/80 registration number and the return address to be used. .

Apparat will perform a full diskette COPY (without CBF option) from its then master onto your diskette, such that all NEWDOS/80 module mandatory zaps then outstanding will be included on your diskette. Your diskette will then be returned via UPS if possible (we can trace UPS better than the mail); otherwise the mail will be used. Please, if possible, provide us with a street address.

The original diskette must still contain its original label with the registration number, which will be checked against your registration card. The diskette must also contain the NEWDOS/80 system. If the registration number is missing or the diskette does not contain the system, the update will be denied. The $10.00 service and handling charge applies each time an original NEWDOS/80 diskette is submitted and it must accompany the diskette. Be certain all non-NEWDOS/80 modules that you wish to keep have been taken off the diskette before sending it. If your original diskette is unchanged, then you have nothing to take off.

This zap update service includes the mandatory zaps to NEWDOS/80 modules only. It does not include optional zaps or zaps to non-NEWDOS/80 modules (i.e., SCRIPSIT, EDIT, etc.). This service does NOT include an upgrade to a new version of NEWDOS, if and when that occurs.

Do NOT send your diskette back to your dealer as dealers are not kept up to date on the current zaps. Send your diskette only to Apparat.

All users keep many copies of NEWDOS/80, and single drive users are forced to have a NEWDOS/80 system on every diskette they use with NEWDOS/80. Once the new zaps have been installed correctly on one copy of NEWDOS/80 and these new zaps have been checked out, the user is now faced with the task of either zapping all the other diskettes or with copying the zapped files to those other diskettes. Through use of format 6 COPY (CBF) with the ILF and DFO parameters (the DFO parameters is defined below and not with COPY). Instead of specifying this procedure, the following example will be used instead.

Suppose that the modules SYS0/SYS, SYS2/SYS, SYS17/SYS, SYS14/SYS, BASIC/CMD, and DIRCHECK/CMD were changed by the latest zaps. The zaps were applied to one copy of NEWDOS/80, and NEWDOS/80 was then checked out to make sure the zaps were OK. For the rest of this example, this diskette is referred to as the zapped diskette.

An ILF file (which is just like a chain file) is built containing the following records.

SYS0/SYS
SYS2/SYS
SYS17/SYS
SYS12/SYS
BASIC/CMD
DIRCHECK/CMD

This file is named ZAPNAMES/ILF and is placed on the zapped diskette. Next, a chain file is built containing one of the following two commands:

COPY,0,0,,NFMT,DFO,CBF,ILF=ZAFNAMES/ILF:0      single drive systems

or

COPY,0,1,,NFMT,DFO,CBF,ILF=ZAPNAMES/ILF:0      two drive systems

This file is named ZAPDUP/JCL and is stored on the zapped diskette. Both of these files can be built using CHAINBLD (see section 6.6) or SCRIPSIT.

The zapped diskette will be considered both the SYSTEM and the SOURCE diskette and will be mounted on drive 0. The NEWDOS/80 diskette to receive the zapped modules will be considered the destination diskette, and, in the case of two drive systems, it will be mounted on drive 1.

Then, for every NEWDOS/80 diskette that is to receive the zapped modules, execute the DOS command:

DO ZAPDUP

This DO command will cause execution of the COPY command contained in file ZAPDUP/JCL:0. Since the COPY command specifies an ILF file, only the files listed in that ILF file will be copied. Further, since the DFO option was specified, only those of the six files previously existing on both the destination and source diskettes are copied. For example, if DIRCHECK/CMD was not previously on the destination diskette, it is not copied to it.

Single drive system users will have to do a lot of diskette mounting. It is best to put a special marking on the zapped diskette to distinguish it from all the others.

Two drive system users will have only two responses per diskette copy.

Since the DFO (Destination Files Only) option was not defined in COPY, it is defined here to mean that only files already existing on the both the destination and the source diskette are copied.

This chapter contains Version 1 to Version 2 conversion information, miscellaneous information and changes to the information contained in other chapters as those chapters were already sent to the printers before the changes could be made.

In late July, Apparat became aware that beginning with the Model III TRSDOS Version 1.3, TRSDOS is using RBA (Relative Byte Addressing) as the format for the EOF field in the directory FPDEs and for the EOF and NEXT fields in the FCBs. Finally, after 28 months, one of the major incompatibilities between NEWDOS and TRSDOS, that of the different handling of the FCB NEXT and EOF fields, will be mostly, if not fully, eliminated.

See section 5.7 for discussion of the FPDE EOF field in the 4th, 21st and 22nd bytes. See section 5.9 for discussion of the FCB EOF field in the 9th, 13th and 14th bytes and the FCB NEXT field in the 6th, 11th and 12th bytes.

See section 12.4 for NEWDOS/80 Version 2 incompatibility with Model 1 TRSDOS Version 2.3.

See section 12.5 for NEWDOS/80 Version 2 incompatibility with Model III TRSDOS Version 1.3.

TRSDOS’s changing of the FPDE EOF field to RBA format is the correct move to make, but it has the unfortunate problem of making Model III TRSDOS 1.1 and 1.2 diskettes not directly readable on 1.3 and vice versa. Feeling that the 1.3 directory structure will become the Model III standard despite all complaints, the functions of the NEWDOS/80 COPY command (see section 2.14) that allow copying of files from and to Model III TRSDOS diskettes will work with the Model III TRSDOS 1.3 diskettes only.

When RBAs were instituted in March, 1979 as the NEWDOS format for the FCB NEXT and EOF fields, we also wanted to set the directory FPDE EOF fields to RBA format. Doing so would have made all NEWDOS diskettes incompatible with all existing TRSDOS diskettes and seriously reduced NEWDOS’ useability. Since there are very few programs that actually read or write the directory FPDE EOF field and since the reason for changing to RBA formats is to eliminate confusing situations that could occur in FCB processing, Apparat decided to leave the directory FPDE EOF field alone. The procedure for converting from the FPDE EOF format used by NEWDOS and the old TRSDOSs to RBA format and vice versa is simple enough and doesn’t cause confusion. The rules are:

To convert from the NEWDOS and old TRSDOS format to RBA format: if the lower order byte of the 3 byte value is non-zero, subtract 256 from the 3 byte value (or subtract 1 from the high order 2 byte value).

To convert from RBA format to the NEWDOS and old TRSDOS format: if the lower order byte of the 3 byte RBA value is non-zero, add 256 to the 3

Byte RBA value (or add 1 to the high order 2 byte value).

Even though at this time there are rumors of Model III compatible TRSDOS coming out for the Model I that will use the RBA format in the directory FPDE EOF field and even though Apparat agrees that that field should be in RBA format, NEWDOS/80 for Version 2 will remain with the old format for that field.

1. Most programs that worked on Model I NEWDOS/80 Version 1 will work on the Model I NEWDOS/80 Version 2.
2. The BREAK key enable/disable can no longer be controlled via bit 4 of 4369H. User program may continue to toggle this bit, but DOS ignores it. See section 2.8.
3. FCB changes (see section 5.9):

1. Use of bit 2 (indicating track and sector operations) of FCB’s 1st byte has been dropped.

2. New definitions have been created for bit 3 of the FCB’s 2nd byte and for bits 7 -5 of the FCB’s 3rd byte.

3. FCB’s 17th through 32nd bytes have been redefined.

4. Directory changes (see sections 5.6, 5.7 and 5.8):

1. The GAT sector now accounts for lumps instead of tracks. Each byte within the 00 – BF range in the GAT now corresponds to a lump rather than a track, and granules per lump rather than granules per track is now used. The first byte of each extent element within FPDE’s and FXDE’s is now a lump number rather than a track number. The 3rd byte of the diskette’s first sector (the boot sector) is now a lump number rather than a track number. Provided the proper GPL value is specified in PDRIVE, all Version 1 directories and boot sector 3rd bytes are directly usable on Version 2 and, with greater care, vice versa.

2. Bits 7, 6 and 5 of the FPDE 2nd byte have been defined.

3. The granule allocation table can now optionally use the first 192 bytes of the GAT sector. If the diskette’s lump count is greater than 96 (60H), the granule allocation has overflowed into and negated the granule existence table (the lockout table).

5. DEBUG can no longer be enabled/disabled by the value in 4315H. User programs can continue to set this location, but DOS ignores it.
6. DEBUG can no longer be entered by pressing the BREAK key; only the 123 keys are used (see section 4.1).
7. PDRIVE has been greatly altered. Study section 2.37 carefully. The following PDRIVEs must be used to read and write existing Version 1 diskettes on Version 2. These specifications must be used when making a diskette that will be read on Version 1.

1. PDRIVE,dnl,dn2,TI=A,TD=A,TC=35,SPT=10,TSR=3,GPL=2,DDS.L=17,DDGA=2 is the specification for standard 5 inch, single density single sided diskettes. For 40, 77 or 80 track drives, set TC accordingly.

2. PDRIVE,dnl,dn2,TI=A,TD=C,TC=80,SPT=20,TSR=3,GPL=4,DDSL=17 ,DDGA=2 Use this DPRIVE setting for 5 inch, single density, double sided diskettes. For 35, 40 or 77 tracks, set TC accordingly.

3. PDRIVE,dnl,dn2,TI=B,TD=B,TC=77,SPT=15,TSR=3,GPL=3,DDSL=17,DDGA=2 is the specification for 8 inch, single density, single sided diskettes used with the OMIKRON interface. Version 2 can handle up to SPT=17 for this type of diskette; you may want to covert your existing diskettes to gain the extra 12 percent space.

4. PDRIVE,dnl,dn2,TI=B,TD=D,TC=77,SPT<30,TSR=3,GPL=6,DDSL

5. PDRIVE,dnl ,dn2,TI=CK,TD=E,TC=34,SPT=18,TSR=3,GPL=2,DDSL=17,DDGA=2 is the specification for 5 inch, single sided, double density diskettes with the PERCOM douber interface. For 40, 77 and 80 track drives, set TC to 39, 76 and 79 respectively. If LNW interface, use TI=EK; if that doesn’t work, try TI=CK.

6. NOTE!!! inch, double sided, double density diskettes used on NEWDDOS/80 Version 1 cannot be used on Version 2. The files on these diskettes must be moved, while using NEWDOS/80 Version 1, to either double sided, single density or single sided, double density diskettes, which can be used with Version 2. Once this is done, the file may be copied to a Version 2 double sided, double density diskette.

8. 5 inch double density diskettes are supported in Version 2 for the PERCOM and LNW double density modifications.
9. SYSTEM has been greatly expanded. Study section 2.46 carefully.

1. Options AH and AK are dropped. Options AT through BN, except BL, have been added.

2. Option BN decides whether NEWDOS/80 is to write single density directory sectors to be readable by Model I TRSDOS or readable by Model III NEWDOS/80. One or the other is allowed but not both.

3. Option BJ allows NEWDOS/80 disk delay timing loops to be increased so that CPU speed up modifications can be active during disk I/O. NEWDOS/80 can handle most CPU speed ups, but it cannot tolerate any slowdown of the CPU below the standard 1.77 2 megahertz speed.

10. COPY has been considerably changed. Study carefully section 2.14.

1. CBF will work even though the system diskette must be dismounted or if all three diskettes will use the same drive.

2. If you are using CBF (format 6) to copy the NEWDOS/80 Version 2 system to another diskette, then you MUST specify the FMT option. If you don’t, the BOOT/SYS and DIR/SYS information may be wrong. If you are simply copying one or more of the system files to an existing system diskette (existing in the sense that it can already boot properly on the drive it is supposed to boot on) then’ you do not need to specify FMT. This information was not included in the CBF documentation and should have been.

3. COPY allows files to be copied back and forth between a NEWDOS/80 Version 2 diskette and a Model III TRSDOS Version 1.3 or higher diskette provided the proper PDRIVE setting is used (see PDRIVE TI flag M).

11. The DOS system ID formerly at location 403EH is now shifted to 4427H. In Version 1, 403EH contained either 80 (50H) or 128 (80H). In Version 2, location 4427H contains 130 (82H) identifying NEWDOS/80 Version 2, and location 442BH contains 01 if Model I and 03 if Model III.
12. None of the NEWDOS/80 Version 1 modules, including all the system modules, the BASIC modules and all other programs supplied on the master diskette, can be used with NEWDOS/80 Version 2. Therefore, the user files on Version 1 system diskettes must be copied to Version 2 system diskettes without copying any of the old Version 1 modules. For single drive users, this is a monumental task, but even multi-drive users must convert more than one system diskette. For each such system diskette, you may use the following procedure to copy your files.

1. Using a copy of the zap updated NEWDOS/80 master system diskette as both the system and source diskette, make another copy of that diskette using format 5 or format 6 COPY with the FMT option specified.

2. Kill off NEWDOS/80 Version 2 files that you do not want to keep. You could have effectively done this by using the ILF parameter in the above COPY, if that copy was format 6. Your ILF file can be built starting with the NWD82V2/ILF file provided on your NEWDOS/80 Version 2 master diskette and, using CHAINBLD/BAS or SCRIPSIT to delete lines for unwanted files. Remember to save the resulting file under a different name, which you will refer to in the ILF parameter of the COPY.

3. Using the resulting diskette again as the destination diskette and the old Version 1 diskette as the source diskette, perform a format 6 copy with the NFMT and the XLF=NWD82V2/XLF:0 parameters. This will copy all of your files from the Version 1 to the Version 2 diskette but will not copy any of the NEWDOS/80 Version 1 files, since they were all excluded by the XLF file. The file NWD82V2/XLF was included on the NEWDOS/80 Version 2 diskette exactly for this purpose and can be inspected via SCRIPSIT or CHAINBLD/BAS.

4. If you wish to copy the resulting Version 2 system diskette that now has your files as well back onto the old Version 1 diskette, you should do so using a format 5 or format 6 copy with the FMT option specified. This gets the Version 2 system and your files back onto the diskette with the old label.

1. Most of section 12.2 applies here; read that section before reading this one. This section will deal only with Model III specifics.
2. Most user programs that were zapped to work with NEWDOS/80 Version 1 will work on the Model III NEWDOS/80 Version 2 with the following corrections :
1. All references to any bytes in the location range 4300R – 43FFH must be dropped or changed to different appropriate locations. This area is now the system sector buffer instead of the 4200H – 42FFH area used by Version 1.
2. The use of 4315H to toggle DEBUG must be dropped altogether.
3. The byte at 4312H used to enable/disable the BREAK key has been shifted to 4478H. The toggling of bit 4 of location 4369H must be dropped altogether.
4. The location of HIMEM has been shifted from 4049H – 404AH to 4411H – 4412H.
5. The location of the CLOCK has been shifted from 4041 – 4043H to 4217H – 4219H. 6. The location of the DATE has been shifted from 4044H – 4046H to 421AH – 421CH.
6. The 25ms one byte cyclic counter has been shifted from 4040H to 441FH. The user timer interrupt routines still cycle based on 25ms increments even though the interrupts really occur every l/30th or 1/125th of a second.
7. The 4410H vector used to insert a timer interrupt routine into NEWDOS/80’s queue has been changed to 447BH (see section 3.8).
8. The DOS command buffer has been changed from starting at 4318H to start at 4225H.
3. 3. – The Model III NEWDOS/80 Version 2 diskette directories are in Model I NEWDOS/80 Version 2 format and are NOT compatible with Model III TRSDOS diskettes.
4. 4. – The Model III NEWDOS/80 Version 2 FCB format is the same as for the Model 1 NEWDOS/80 Version 2 and is NOT compatible with the Model III TRSDOS FCB format.
5. 5. – The following PDRIVE specifications must be used to read and write existing Version 1 diskettes on Model III Version 2. These specifications must be used when making a diskette that will be read on Version 1.
1. PDRIVE,dnl,dn2,TI=AK,TD=E,TC=39,SPT=18,TSR=3,GPL=2,DDSL=17, DDGA=2 is the specification for 5 inch, single sided, double density, 40 track diskettes. For 35, 77 or 80 tracks, set TC to 34, 76 and 79 respectively.
2. PDRIVE,dnl,dn2,TI-A,TD=A,TC=80,SPT=10,TSR=3,GPL=2,DDSL=17,DDGA=2 is the specification of a 5 inch, single sided, single density diskette. For 35, 40 or 77 track drives, set TC accordingly.
3. PDRIVE,dnl,dn2,TI=A,TD=C,TC=80,SPT=20,TSR=3,GPL=4,DDSL=17,DDGA=2 is the specification of a 5 inch, double sided, single density, 80 track diskette. For 35, 40 and 77 track drives, set TC accordingly
4. NOTE!!! 5 inch, double sided, double density diskettes used on NEWDOS/80 Version 1 cannot be used directly on the Model III. See section 12.2.7.6.

1. NEWDOS/80 maintains the NEXT field of the FCB in RBA format at all times. TRSDOS 2.3 maintains the NEXT field as an RBA whenever the lower order byte equals 0 or whenever the current write position is within a buffer that has been changed but not yet updated. In most other cases, TRSDOS tends to maintain the NEXT field equal to the RBA plus 256. At any one time, there is some confusion just what the NEXT field really means.
2. NEWDOS/80 maintains the EOF field of the FCB in RBA format at all times, and it updates the FCB EOF field for each byte written to the file, if indeed the EOF is to be changed. TRSDOS 2.3 updates the EOF only when the sector is actually written, though the low order byte is updated continuously during single byte or logical record writes. Thus if the current record would cause a change in EOF, EOF has two possible values, depending upon whether the current sector has pending data awaiting write or the current sector has already be written. Normally TRSDOS’s FCB EOF value is an RBA value if the low order byte equals 0 and RBA plus 256 if the low order byte is non-zero.
3. Enabling or disabling of DEBUG in TRSDOS is still done by setting the byte at 4315H which is ignored in Model I NEWDOS/80 and must not be done in Model III NEWDOS/80.
4. Activation and deactivation of timer routines is done differently in the two systems (see sections 3.8 and 3.9 for the NEWDOS/80 methods).
5. Both Model I TRSDOS and NEWDOS/80 use essentially the same directory format except that TRSDOS is still limited to 35 track diskettes and a two granule directory and that NEWDOS/80 uses some previously unused bytes and bits.
6. The following is a list of routines defined in chapter 3 that are common to both NEWDOS/80 Version 2 and Model I TRSDOS 2.3. Each routine performs nearly the same in both systems. The other chapter 3 routines are either not used in Model I TRSDOS or are defined for different functions. These common routines are:

0013H, 001BH, 402DH, 4030H, 4400H, 4405H, 4409H, 440DH, 441CH, 4420H, 4424H, 4428H, 442CH, 4430H, 4433H, 4436H, 4439H, 443CH, 443FH, 4442H, 4445H, 4448H, 4467H, 446AH, 446DH, 4470H, 4473H

1. Model III TRSDOS diskettes are totally incompatible with NEWDOS/80 Version 2 diskettes. 5 inch, single density, single sided, 35 track diskettes with a two granule directory starting on lump 17 can be processed with Model III TRSDOS’s convert program. Also, files can be copied back and forth between NEWDOS/80 Version 2 diskettes and Model III TRSDOS Version 1.3 or higher diskettes providing the PDRIVE specifications for the Model III TRSDOS diskette include the TI flag M.
2. Model III TRSDOS Version 1.3 has gone to using RBA values in the NEXT and EOF fields of the FCB and the EOF field of the directory. With this change to the FCB processing, NEWDOS/80 and TRSDOS has become more compatible than previously though, at this printing, just how close is not yet clear.
3. Model III TRSDOS uses a 50 byte FCB whereas NEWDOS/80 Version 2 stays with the old 32 byte format. NEWDOS/80 can use the 50 byte FCB area, but TRSDOS will clobber the 18 bytes following a 32 byte FCB. Users should study the specifications of the FCB’s between the two systems as the differences are not detailed here.
4. The byte used to enable or disable the BREAK key is at 42AEH for Model III TRSDOS whereas it is as 4478H for Model III NEWDOS/80 and 4312H for Model I NEWDOS/80. If the byte equals 0C9H the BREAK key is enabled, and if the byte equals 0C3H the BREAK key is disabled.
5. The following is a list of the routines defined in chapter 3 that are common to both NEWDOS/80 Version 2 and Model III TRSDOS. Each routine performs nearly the same in both systems. The other chapter 3 routines are either not used in Model III TRSDOS or are defined for different functions. These common routines are:
   0013H, 001BH, 402DH, 4030H, 4409H, 440DH, 441CH, 4420H, 4424H, 4428H, 442CH, 4430H, 4433H, 4436H, 4439H, 443FH, 4442H, 4445H, 444811.
6. Refer to section 7.13 for comparison of the BASIC CMD functions offered in NEWDOS/80 with those offered for Model III TRSDOS.
7. Routing is handled somewhat differently in the two systems. Straight forward applications should be all right. DUAL is not implemented in NEWDOS/80.

1. A very few users have coded system routines to be loaded by DOS’ sys tem routine loader, and these users should be aware that NEWDOS/80 Version 2 uses the system FPDE slots through SYS21/SYS. Whereas NEWDOS/21 and TRSDOS were limited to 14 system programs loadable by the system program loader NEWDOS/80 allows for 30 with FDE slot assignment continuing the same order established by the old TRSDOS. The code to activate a routine in one of these directory position dependent system modules is sent to the system in register A, must be greater than 1FH and in uuubbsss 8 bit for mat where:
   
   sss+2 = the relative sector in the directory containing the FDE.
   bb times 32 (20H) = the offset in the sector to the FDE.
   
   uuu = a user defined code greater than 0.
   
   A future release of NEWDOS will use system programs from SYS22/SYS and up; users should start from SYS29/SYS down.
2. All NEWDOS80 support programs use HIMEM high memory value in Model I locations 4049H-404AH (Model III locations 4411H-4412H) as upper memory limit.
3. (Model I only) During power on, reset or a jump to location 0, control is passed to the ROM. To determine if the disk controller is present, the ROM tests the contents of location 37ECH, the disk controller status byte. If the value is either 00 or FFH, ROM assumes a non-disk system and proceeds to initialize non-disk level II BASIC. However, 00 is a valid disk controller state, meaning that the controller has no status and the drives are ready (the light is on). To avoid this unwanted entry into non-disk BASIC, wait until the ready light goes off before pressing reset.
4. To speed up disk operations when additional file space is allocated to a file, NEWDOS/80 allocates up to 4 granules at one time. There is a disadvantage to this, however. If two or more new files on the same diskette are open at the same time, it is quite possible to run out of file space, close all the files and then find out the diskette now has space, as CLOSE released the extra granules that files had allocated but not yet used.

Understanding and learning to use the marked item and fixed item files specified in chapter 8 has proved difficult to the normal NEWDOS/80 user; therefore appendices A and B have been included to provide examples and more explanation in an effort to ease this difficulty. Nothing in appendix A or B is to be construed as overriding the specifications provided in chapter 8; the two appendices are provided simply and exclusively for examples and elaboration.

Appendix A was written by a user trying to cope with chapter 8 and is basically his understanding of marked item and fixed item files.

Appendix B is the NEWDOS/80 author’s attempt to provide example programs of the 5 file sub-types: MF, MU, MI, FF and FT.

File Positioning

File Position (fp) is an operand in all NEWDOS/80 GETS and PUTS, and is specified in section 8.4.1. When omitted, a null operand is assumed. The fp operand otherwise commonly consists of a special character, occasionally followed by other special characters and/or expressions. One form of the fp operand consists of nothing more than a numeric expression. In the forms which follow, special characters are to be used as shown. In those forms showing a prefixing special character adjoining some other character string, the special character does not necessarily have to be contiguous with the rest of the expression; it may be separated from it by a blank or space.

As mentioned above, certain forms for fp change REMBA, REMBRA or EOF. For your convenience, the fp forms and their effects on these fields are summarized in the following decision table.

fp         REMBA      REMRA      EOF
(null)     1          1          6
*          1          2          6
#          3          4          6
$          4          4          6
%          4          4          4
&          4          4          4
&&         4          4          4
!RBA       1          1          6
!%         1          1          6
!$RBA      5          5          4
!$%        5          5          4
!#RBA      4          4          1
RN         1          1          6

Meanings of codes in the matrix:

1 – – The field is set to the RBA resulting from that: fp value.

2 – – If REMRA is invalid at the beginning of the statements execution, or it is an HI or FI file, the field is set to the RBA resulting from the fp value. fn other words, it is set if the current file position is at the beginning of a record, otherwise it is unchanged.

3 – – The field is set equal to REMBA.

4 – – The field is not changed.

5 – – The field is set to an invalid value.

6 – – For output/update files, the field is changed if a PUT extends the file.

Altogether, there are four areas in an FCB relevant to file positioning. These are:

Current File Position

This single field can be looked at as being 3 different values, depending upon where the GET/PUT is in its processing:

GPP1

The file position at the start of GET/PUT execution. Unless the file has been closed and re-opened, it is the same value left as GPP3 from the last GET/PUT for that filearea.

GPP2

The resulting RBA value after positioning has been done, and prior to any data transfer, GPP2 is the value saved as REMBA and REMRA whenever these values are set.

GPP3

The RBA value after the last byte of data transfer, if any, real or byassed, has been accomplished.

REMRA

For MU, MF, FF and field item type files, it contains the RBA value of the beginning of the record in process., For MI, FI and INPUT/PRINT files, it is equal to REMBA. See GPPP above.

REMBA

The RBA value where the previous data-transferring GET/PUT began its data transfer. If the file is record-segmented, and REMBA is at the start of a record, REMRA is set equal to REMBA. See GPP2 above.

EOF

The RBA value of the last byte of data in the file, plus 1. For MU, MF, FF and field item type files, it effectively points to the next sequential record to be written to the file. For MI, FI and INPUT/PRINT files, it effectively points to the next sequential byte to be written to the file.

The general method of managing the various fp values in the FCB goes as follows:

The file is moved from the current file position (GPP1) t o the requested position, if necessary. This may include writing an updated buffer back to the diskette, computing the new sector address, and reading that sector into the buffer.

The RBA resulting from the requested positioning is placed in the current file position (GPP2).

RMBA is set equal to the current file position (GPP2).

If the file is an INPUT/PRINT file, is user-segmented, or is record-segmented and the current file position (GPP2) points to the start of a record, REMRA is set equal to the current file position (GPP2).

Data transfer, if any is requested, is done. The current file position (GPP3) contains the RBA of the byte following the last one transferred.

If the file has been extended, or the fp = !#rba, EOF is set to the appropriate value of the two.

*** APPENDIX A IS 47 PAGES … THIS IS WHERE I STOPPED.

The purpose of this appendix is to give some examples of marked item and fixed item file useage and to give different explanations than were offered in chapter 8 and Appendix A. Chapter 8 contains the specifications for the I/O enhancements to BASIC. This appendix hopes to give enlightment but is not the specifications ; chapter 8 is!!!

Thoughout this appendix (as well as the whole manual) we shall refer to the file types by their short names. The reader should refer now to the glossary in chapter 10 for the definitions of MI file, MU file, MF file , FI file, and FF file. This appendix will also refer to other terms such as IGEL, RBA, REMRA, REMBA, etc. which are defined in the glossary or in chapter 8.

Most of the examples given in this appendix deal with MU files and FF files since these two types will be the most commonly used by the programmers.

We have tried to make the examples as much a like as possible or practical to make it easier for the reader to spot the differences.

Since we are basically interested in demonstrating the use of the files (an exception is the demonstration of the uses of CMD”O”,BASIC’s in-memory sort), we do not provide the routines which actually use or generate the data to be read from or sent to the files. The programmer is assumed to provide these routines if he/she wishes to use these examples in live situations.

In all these examples, each named variable corresponding to a file item is suffixed with an explicit type symbol ($, %, ! or #) (see line 120 of Example 3). This is done so that the reader will know exactly what type of data is being read from or written to the file. We STRONGLY recommend that in your own IGELs you do the same thing; otherwise it is quite possible that you can severly damage a file by the implied type not being as you thought you remembered it. Use of explicit type symbols was required in version 1 for IGELs used in fixed item file processing, but that is not so in version 2. An example of an IGEL that does not use explicit type symbols is to change two lines in Example 7 to be:

10 CLEAR 2000: DEFSTR N, S: DEFINT A , I : DEFSNG F: DEFDBL D
120 (20)NM,AN,AM!,DT,(15)ST,IG,FP,DP;

Remember, we STRONGLY recommend the suffixing of type symbols to the variable names in IGELs.

The operation of a GET or a PUT proceeds in two phases:

1. The file positioning phase. In this phase, the file is positioned according to the second parameter, the file positioning parameter, of the GET or PUT statement. At the end of this phase, for certain types of positioning parameters, the file 1ocation values REMRA and REMBA are saved for possible future use when the subsequent positioning parameter for that file area is # or $ (see section 8.10).
2. The data transfer phase. In this phase, data is transferred between the file and the variables named in the IGEL.

Example 1: Write records sequentially to a MU file.

MU files are intended as an alternative to print/input files. A MU file tends to use less disk space than a print/input file, can be updated with some restrictions, can be indexed into via the !rba positioning parmeter, and does not need the ;”,”; character sequence to separate strings during writes to the file.

10 CLEAR 2000
20 OPEN "O",1,"XXX/DAT:1",MU
30 GOSUB 10000 'build data for record
40 IF RN% = 0 THEN CLOSE : END    'end of run
50 PUT 1,,,NM$,AM!,DT#,ST$,IG%,FP!,DP#;
60 GOTO 30

The file is opened for sequential output of records whose individual lengths vary degending upon the size of the two strings contained in each record.

The file positioning parmeter in the PUT statement is null, indicating that each execution of that PUT writes the next sequential record.

The programmer supplies the routine at 10000 to generate the data for the records. If no more records are to be created, set RN% = 0. Otherwise set RN% not 0 and put into the 8 variables NM$, AN%, AM!, DT#, ST$, IG%, FP! and DP# the data that is to be transmitted to the file.

The IGEL in this example is contained within the PUT statement and consists of 8 expressions (in this case, all named variables). The variable or expression associated with each record item is separated from its neighbor by a comma. The IGEL is teminated by a semicolon.

The full contents of each of the strings NM$ and ST$ is sent to the file, with each preceded by one or two string marker bytes. The second marker byte is used for strings 128 to 255 characters in length.

Each of the integers AN% and IG% is represented in the file as 3 bytes, a 72H marker byte followed by the 2 bytes of the binary integer value in the same format as used by BASIC.

Each of the single precision floating point numbers AM! and FP! is represented in the file as 5 bytes, a 73H mrker byte followed by the 4 byte binary single precision floating point value in the same format as used by BASIC.

Each of the double precision floating point numbers DT# and DP# is represented in the file as 9 bytes, a 74J marker byte followed by the 8 byte binary doubleprecision floating point value in the same format as used by BASIC.

Using the IGEL in the PUT statement to compute the minimum and maximum record lengths, the minimum length of a record in this file will be 37 bytes (both strings are null and including the SOR byte) and the maximum length of a record will be 549 bytes (both strings have 255 characters).

Example 2: Read records sequentially from a MU file.

10 CLEAR 2000
20 OPEN"I",1,"XXX/DAT:1","MU"
30 IF EOF (1) THEN END
40 GET 1,,,NM$,AN%,AM!,DT#,ST$,IG%,fp!,dp#;
50 GOSUB 10000  'process the record's data
60 GOTO 10

This example is the opposite of Example1, using the same IGEL and named variables, The data records of the file are successively read and processed. The programmer supplies the routine at 10000 to do what he/she wishes with the data.

The file positioning parameter in the GET statement is null, meaning that each execution of that GET reads the next sequential record in the file.

The EOF(1) function returns a true condition when the file position of the next record is exactly at file EOF,

Example 3: Sequentially read and update the records of a MU file.

10 CLEAR 2000
20 OPEN "R",1,"XXX/DAT:1","MU"
30 IF EOF(1) THEN END40 GET 1,,120  'Read the next sequential record
50 GOSUB 10000
60 PUT 1,#,120
70 GOTO 30
120 NM$,AN%,AM!,DT#,ST$,IG%,FP!,DP#;

The same file created in Example 1 is used in this example, The file is opened for both input and output operations. Records are read sequentially from the file into the BASIC variables, zero or more of those variables are updated by the programmer supplied routine at statement 10000, Upon return from that routine, the record is written back to the file.

The file positioning parameter in the PUT statement is the character 8. For this example, at the start of each execution of that PUT statement, the file is repositioned back to the start of the record read by the GET, causing the PUT to update that record.

Both the GET and the PUT statement use the same IGEL which is located at text line 120. This IGEL is identical to that used in examples 1 and 2 except that instead of being contained within the GET or PUT statement, it is contained in a separate text line with the GET and PUT statements containing that line number as their third parameter.

An error will be declared if the PUT statement finds the new length of a record exceeds the length originally assigned to that record during Example 1. This will only occur when the sum total of the file space used by the record’s string items exceeds that of what the strings originally occupied plus any null space included in the original record (insertable using the (len)# function, see section 8.4.3.4). The numeric values may be updated without concern as they always occupy the same amount of file space, Thus, if a string item is to be updated in a MU file , the string’s resulting length should not be increased; it can be, but be careful,

Example 4: Read in, sort in memory and write back out a MU file.

10 CLEAR 10000 : DEFINT I
15 DIM NM$(200), AN%(200), AM!(200), DT#(200)
17 DIM ST$(200), IG%(200), FP!(200), DP#(200), IX%(200)
18 DIM IX%(200)
20 IX=0 : OPEN "I",1,"XXX/DAT:1","MU"
30 IF EOF(1) THEN 80
40 IX = IX + 1 : IF IX >200 THEN PRINT "TOO MANY RECORDS" : END
50 GET 1,,60 : GOTO 30
60 NM$(IX),AN%(IX),AM!(IX),DT#(IX),   'IGEL 1st line
70 ST$(IX), IG%(IX), FP!(IX), DP#(IX);  'IGEL last line
80 IF IX = 0 THEN PRINT "EMPTY FILE" : END
90 CMD "O",IX,*IX%(1),AM!(1),NM$(1)
100 CLOSE : OPEN "O",1,'XXX/DAT:1","MU"
110 IY = IX : FOR IZ = 1 TO IY
120 IX = IX%(IZ) : PUT 1,,60
130 NEXT IZ : CLOSE : END

The MU file XXX/DAT:1 of 1 to 200 records is read into 8 arrays.

The records are then indirectly sorted at line 90 using BASIC’s array sort using the IX% array as the interger indirect array. The sorting criteria is ascending order, first by the AM! values and then by the NM$ values. During the sort , the integer IX% array is set up to contain sequentially in the sorted order the index values into the other arrays,

It should be noted that the sort changed nothing in the record arrays AM! and NM$. The IX% array was initialized to point each successive element to successive elements of the AM! array. As the sort proceded, the elements in the IX% array were moved around to confom to the sort order.

It should further be noted that though the file records span across 8 arrays, the sort saw only the two of them (AM! and NM$) that provided the sort data.

After the sort the records of the file are written out in sorted order. Since the same file was used to store the sorted records, the user must be sure to preserve a backup copy of the original file in ease an error occurs during the output of the sorted records.

This example demonstrates that IGELs can contain array named variables and that an IGEL may span multiple text lines (lines 60 and 70).

Example 5: Write records sequentially to a FF file.

FF files are intended as an alternative to field item files (TRSDOS random files). The FIELD statement is not used with FF files; though the user may wish to use the pseudo FIELD function specified in section 8.11. LSET and RSET are not used in FP file processing to set up the variables making up the record, though if the user has set the strings to the specified lengths via the pseudo FIELD function, he/she may wish to use LSET or RSET to maintain a string variable at that length. LSET and RSET must never be used for numeric variables. For FP files, MKD$, MKI$, MKS$, CVD, CVI and CVS are not used.

Each string variable in the IGEL must be prefixed with the length the string item will have in the file, and regardless of the number of characters in the variable’s string at the time of the PUT, the corresponding string in the file will be truncated on the right or padded on the right with spaces to make up the required number of characters. During the PUT, the string variable is NOT changed; only the file item is.

10 CLEAR 2000
20 OPEN "O",1,"XXX/DAT:1","FF",63
30 GOSUB 10000
40 IF RN% = 0 THEN CLOSE : END  'ALL DONE
50 PUT 1,,,(20)NM$,AN%,AM!,DT#,(15)ST$,IG%,FP!,DP#;
60 GOTO 30

The file is opened for sequential output of records each 63 bytes long.

The file positioning parameter in the PUT statement is null, indicating that each execution of that PUT writes the next sequential record.

The programmer supplies the routine at 10000 to generate the data for the records. If no more records are to be generated, set RN% = 0. Otherwise set RN% non-zero and load the 8 variables NM$, AN%, AM!, DT#, ST$, IG%, FP! and DP# with the data that is to be transmitted to the file.

The IGEL is contained within the PUT statement and consists of 8 named variables. The name variable associated with each record item separated from its neighbor by a comma. The IGEL is terminated by a semicolon.

Each of the strings NM$ and ST$ is represented in the file by the number of characters specified by the variable’s prefix in the IGEL. For each PUT executed by this example, the current contents of NM$ are sent to the file. If the NM$ string has more than 20 characters, the excess characters on the right are dropped from the file item, not from NM$. If the NM$ string has less than 20 characters, the file item, not NM$, is padded on the right with spaces to make the file item 20 characters long. The same concept holds in restricting to 15 characters the file item associated with the ST$ string.

Each of the integers AN% and IG% is represented in the file by 2 bytes in the same format as used by BASIC.

Each of the single precision floating point numbers AM! and DF! is represented in the file by 4 bytes in the same format as used by BASIC.

Each of the double precsion floating point numbers DT# and DP# is represented in the file by 8 bytes in the same format as used by BASIC.

Example 6: Read records sequentially from a FF file.

10 CLEAR 2000
20 OPEN "I",1,"XXX/DAT:1","FF",63
30 IF EOF(1) THEN END
40 GET 1,,,(20)NM$,AN%,AM!,DT#,(15)ST$,IG%,FP!,DP#;
50 GOSUB 10000   'process the record's data
60 GOTO 30

This example is the opposite of Example 5, using the same IGEL and named variables, The data records of the file are successively read and processed, The programmer supplies the routine at 10000 to process the data.

The file positioning parameter in the GET statement is null, meaning that each execution of that GET reads the next sequential record in the file.

After each record read, AM$ contains a 20 character string and ST$ contains a 15 character string.

Example 7: Sequentially read and update the records of a FF file.

10 CLEAR 2000
20 OPEN "R",1,"XXX/DAT:1","FF",63
30 IF EOF(l) THEN END
40 GET 1,,120 'read the next sequential record
50 GOSUB 10000 'update the record's data
60 PUT 1,#,120 'rewrite the record back to the file
70 GOTO 30
120 (20)NM$,ANZ,AM!,DT#,(15)ST$,IGZ,FP!,DP#;

The same file created in Example 5 is used here. The file is opened for both input and output operations. Records are read sequentially from the file into the BASIC variables, zero or more of those variables are updated by the pro­ grammer supplied routine at statement 10000. Upon return from that routine, the record is written back to the file. ■ The file positioning parameter for the PUT statement is the character #. At the start of each execution of the PUT in this example, the file was reposi­ tioned back to the start of the file record read by the GET (in more compli­ cated words, to the REMRA), thus causing the PUT to write that record.

Both the GET and the PUT use the IGEL starting at line 120.

After each GET, NM$ contains a 20 character string and ST$ contains a 15 char­ acter string. During the programmer supplied processing, the lengths of one or both of the strings may change. During the PUT, the file item corresponding to AM$ is set again to a length of 20 characters, with space padding or truncation taking place on the right as necessary. The same concept applies to the 15 character file item corresponding to ST$. Remember, AM$ and ST$ are not changed by the PUT.

Example 8: Randomly read and optionally update the records of a FF file.

10 CLEAR 2000
20 OPEN "D",1,"XXX/DAT:1","FF",63
30 GOSUB 10000 ' determine which record to read
40 IF RN% = 0 THEN END 'end if no more
50 GET 1,RN%,120 	'read that record
60 GOSUB 15000	 'optionally update the record's data
70 IF RN% <> 0 then PUT 1,RN,120 'if required, write the record
80 GOTO 330
120 (20)NM$,AN%,AM!,DT#,(15)ST$,IG%,FP!,DP#;

This example is similiar to Example 7 excepting that the record reads are done randomly and the programmer can elect not to update the record. The file created in Example 5 is used here. For each record, the processing is as follows:

The programmer supplied routine at line 100ft) determines which file record is to be looked at next. On return, RN% contains the desired record number; if RN%= 0, the run is ended.

The record is read, using RN% as the file positioning parameter to specify which record is wanted.

The programmer supplied routine at line 15000 looks at the record’s data and optionally changes 1 or more variables associated with the record. On exit from the routine, RN% is set to zero if the record is not to be updated; otherwise RN% is unchanged.

If RN% is not zero, the record is rewritten to the file using RN% as the file positioning parameter. Note, the file positioning parameter for the PUT could have been the character #.

Note the use of “D” rather than “R” as the 1st parameter in the OPEN statement. “R” could have been used, but “D” prevents the file from being extended if for some reason RN% was changed before the PUT statement to be a record number beyond the range of the file.

Example 9: Sequentially write records to a MU file and sequentially write records to a FF file that serve as an index into the MU file.

There are many cases where the user has a huge file with each record having strings of varying lengths, does not want the string padding or trucation that is done by field item or fixed item files and yet still wants to be able to randomly access the file, and to a limited extent be able to update that file.

Using a MU file as the main file and an FF file as an index file, the user can achieve these objectives.

10 CLEAR 2000
20 DIM ANZ(4000),RB1(4000) 'two arrays to hold index data
30 OPEN "O",1,"XXX/DAT:1","MU" 'open the main data file
40 RC% = 0
50 GOSUB 10000 'create next record's data
60 IF RN% = 0 THEN 105 'done with main file
70 RC%-RC%+1: IF RCZ > 4000 THEN PRINT "FILE TOO LARGE": GOTO 105
80 RB!(RCZ) = LOC(l)! 'save RBA of next record
90 PUT 1,,,NM$,AN%(RC%),AM!,DT#,ST$,IG%,FP!,DP#;
100 GOTO 50
105 CLOSE
110 IF RCZ - 0 THEN PRINT "NO DATA RECORDS": END
120 CMD"O",RC%,AN%(1),RB!(1) 'sort index data
130 OPEN "O",l,"XXX/NDX:l","FF",6 'open index file
140 FOR X = 1 TO RC%
150 PUT 1,,,AN%(X),RB!(X); 'write index record
160 NEXT X: CLOSE: END

This example could have been programmed to write alternatingly one record to each of the two files. However, since both are on the same drive, the drive arm would be constantly in motion and execution would take, or at least seem to take, forever. Therefore, the index file’s data is stored into arrays to be written out after the main file has been completely written.

For this example the AN% array is assumed to hold account numbers and for each main data file record, the account number is unique.

The program proceeds as follows: For each main data file record:

The programmer supplied routine at 10000 set RN% = 0 if no more main data file records are to be created. Otherwise it sets RNZ non-zero and creates the record’s data by storing the values in the proper variables, including the account number into its array.

The RBA of where that record is to be placed in the main data file is determined by the line 80 LOC(1)! function and is stored into the RBA array RBI.

The record is written to the main data file.

The two arrays AN% and RB! are directly sorted. Since this is a direct sort, both arrays are physically arranged in the sort order, which is in ascending order of account number. Note, though ascending order of RBA is the secondary sort criteria, since the account numbers are unique, the RBA values are never checked.

The index file is created by writing the index records sequentially from the arrays, which are in ascending order of account number.

Exactly the same results would have been attained had text lines 80 and 90 above been written as:

80 PUT 1,,,NM$,AN%(RC%),AM!,DT#,ST$,IG%,FP!,DP#;
90 RB! = LOC(l)#  'RBA where the record was placed

*** APPENDIX B CONTINUES ….

Navigation

Go back to …

Chapter 1: Introduction

Chapter 2: DOS Library Commands

Chapter 3: DOS Routines

Chapter 4: DOS Features

Chapter 5: DOS Modules, Data structures, and Miscellaneous Information

Chapter 6: Additional Programs Supplied on NEWDOS/80 Diskette

Chapter 7: Disk Basic, Non-I/O Enhancements

Chapter 8: Basic Disk I/O Enhancements
and Differences

Chapter 9: Error Codes and Messages

Chapter 10: Glossary

Chapter 11: Error Reporting, Incompatibility Handling,
and Patching.

Chapter 12: Conversion Information
and Miscellaneous Comments.

Appendix A: Appendix A

Appendix B: Appendix B