NEWDOS/80 v2.0 Reference – Chapter 8 Through End

Table of Contents

Chapter 1
Chapter 2
Chapter 3
Chapter 4
Chapter 10
Appendix A
Appendix A (Partial)
Appendix B
Appendix B (Partial)

8. BASIC DISK I/O ENHANCEMENTS AND DIFFERENCES.

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

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

8.3.
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$ 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.

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

8.5.
Fixed item file characteristics
  1. 1. Contains zero or more items.
  2. 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. 3. A file may be subdivided into records all of the same length.
  4. 4. Maximum length of records is 4095 bytes.
  5. 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. 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. 7. Via the GET statement, the contents of fixed item file items are moved into the BASIC variables specified by the IGEL.
  8. 8. Via the PUT statement, fixed item file items are created or replaced from the BASIC variables specified in the IGEL.
  9. 9. BASIC statement CLOSE terminates an I/O link between the program and a fixed item file.
  10. 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. 11. When an FF file record is created, any unused space at the end of the record is filled with zero bytes.
8.6.
Marked item file characteristics:

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.

8.7.
OPEN – DISK BASIC’S OPEN statement has been modified to handle the following formats:
  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.

8.8.
GET DISK BASIC’S GET statement has been modified to handle the following formats:

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

8.9.
PUT: DISK BASIC statement PUT is modified to handle the following formats:

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,!$RBA PUT fan,!$%

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.

8.10.
REMRA and REMBA. Within each filearea’s control data, BASIC saves two additional relative file location values:
  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 = !$RBA or !$% 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.
8.11.
Pseudo FIELD Function: For fixed item and marked item files, the FIELD statement is not legal. However, there are times when the programmer may want to set the strings associated with an IGEL to their specified lengths and keep them that way by using LSETs and RSETs. The user could do this by using the STRING$ function. Another way is to use the psuedo FIELD function having the following formats:
  1. 1. – GET fan,2,IGELSN
  2. 2. – GET fan,%,,IGEL
  3. 3. – PUT fan,%,IGELSN
  4. 4. – PUT fan,%,,IGEL

where:

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

1. Numeric variables are left unchanged.

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

3. String variables in the IGEL must be prefixed.

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

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

8.12.
LOC Function: NEWDOS/80 DISK BASIC has a LOC function defined as follows:
  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.

  1. – 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.

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

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

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

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

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

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

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

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

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

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

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

PUT fan,!#LOC(fan)#

8.14.
Some notes about NEWDOS/80 DISK BASIC I/O.
  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$, MKS$, CVD, CVI,_ CVS, LSET, RSET, etc.) work as before. However, the use of MKD$, 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, &, && 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.

9. ERROR CODES AND MESSAGES.

9.1
DOS Error Codes and Messages.

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.

00 (00H)
No Error
01 (01H)
BAD FILE DATA
02 (02H)
SEEK ERROR DURING READ
03 (03H)
LOST DATA DURING READ
04 (04H)
PARITY ERROR DURING READ
05 (05H)
DATA RECORD NOT FOUND DURING READ
06 (06H)
TRIED TO READ LOCKED/DELETED RECORD
07 (07H)
TRIED TO READ SYSTEM RECORD
08 (08H)
DEVICE NOT AVAILABLE
09 (09H)
UNDEFINED ERROR CODE
10 (0AH)
SEEK ERROR DURING WRITE
11 (0BH)
LOST DATA DURING WRITE
12 (0CH)
PARITY ERROR DURING WRITE
13 (0DH)
DATA RECORD NOT FOUND DURING WRITE
14 (0EH)
WRITE FAULT ON DISK DRIVE
15 (0FH)
WRITE PROTECTED DISKETTE
16 (10H)
DEVICE NOT AVAILABLE
17 (11H)
DIRECTORY READ ERROR
18 (12H)
DIRECTORY WRITE ERROR
19 (13H)
ILLEGAL FILE NAME
20 (14H)
TRACK # TOO HIGH
21 (15H)
ILLEGAL FUNCTION UNDER DOS-CALL
22 (16H)
UNDEFINED ERROR CODE
23 (17H)
UNDEFINED ERROR CODE
24 (18H)
FILE NOT IN DIRECTORY
25 (19H)
FILE ACCESS DENIED
26 (1AH)
DIRECTORY SPACE FULL
27 (1BH)
DISKETTE SPACE FULL
28 (1CH)
END OF FILE ENCOUNTERED
29 (1DH)
PAST END OF FILE
30 (1EH)
DIRECTORY FULL. CAN’T EXTEND FILE
31 (1FH)
PROGRAM NOT FOUND
32 (20H)
ILLEGAL OR MISSING DRIVE #
33 (21H)
NO DEVICE SPACE AVAILABLE
34 (22H)
LOAD FILE FORMAT ERROR
35 (23H)
MEMORY FAULT
36 (34H)
TRIED TO LOAD READ ONLY MEMORY
37 (25H)
ILLEGAL ACCESS TRIED TO PROTECTED FILE
38 (26H)
FILE NOT OPEN
39 (27H)
ILLEGAL INITIALIZATION DATA ON SYSTEM DISKETTE
40 (28H)
ILLEGAL DISKETTE TRACK COUNT
41 (29H)
ILLEGAL LOGICAL FILE #
42 (2AH)
ILLEGAL DOS FUNCTION
43 (2BH)
ILLEGAL FUNCTION UNDER CHAINING
44 (2CH)
BAD DIRECTORY DATA
45 (2DH)
BAD FCB DATA
46 (2EH)
SYSTEM PROGRAM NOT FOUND
47 (2FH)
BAD PARAMETER(S)
48 (30H)
BAD FILESPEC
49 (31H)
WRONG DISKETTE RECORD TYPE
50 (32H)
BOOT READ ERROR
51 (33H)
DOS FATAL ERROR
52 (34H)
ILLEGAL KEYWORD OR SEPARATOR OR TERMINATOR
53 (35H)
FILE ALREADY EXISTS
54 (36H)
COMMAND TOO LONG
55 (37H)
DISKETTE ACCESS DENIED
56 (38H)
ILLEGAL MINI DOS FUNCTION
57 (39H)
OPERATOR/PROGRAM/PARAMETER REQUIRE FUNCTION TERMINATION
58 (3AH)
DATA COMPARE MISMATCH
59 (3BH)
INSUFFICIENT MEMORY
60 (3CH)
INCOMPATIBLE DRIVES OR DISKETTES
61 (3DH)
ASE=N ATTRIBUTE. CAN’T EXTEND FILE
62 (3EH)
CAN’T EXTEND FILE VIA READ

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

SYS4/SYS is the DOS error message display module.

9.2
DISK BASIC Error Codes and Messages.

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

51
FIELD OVERFLOW
52
INTERNAL ERROR
53
BAD FILE #
54
FILE NOT FOUND
55
BAD FILE MODE
56
FILE ALREADY OPEN
58
DOS ERROR
59
FILE ALREADY EXISTS
62
DISK FULL
63
INPUT PAST END
64
BAD RECORD #
65
BAD FILE NAME
66
MODE MISMATCH
67
DIRECT STATEMENT IN FILE
68
TOO MANY FILES
69
DISK WRITE PROTECTED
70
FILE ACCESS DENIED
71
SEQ # OVERFLOW
72
RECORD OVERFLOW
73
ILLEGAL TO EXTEND FILE
75
PREVIOUSLY DISPLAYED ERROR
76
CAN’T PROCESS LINE 0
77
BAD FILE TYPE
78
IGEL SYTAX ERROR
79
IGEL ITEM SYTAX ERROR
80
BAD/ILLEGAL/MISSING IGEL ITEM PREFIX
84
BAD FILE POSITIONINGPARAM
82
BAD RECORD LENGTH
83
STMT USES 2 FILE NAMES

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.

10. GLOSSARY.

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.


11. ERROR REPORTING, INCOMPATIBILITY HANDLING, AND PATCHING.

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


11.2.
Incompatibility Handling.

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

11.3.
Reporting of NEWDOS/80 Errors and Incompatibilities.

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.
11.4.
Format of NEWDOS/80 Zaps.

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.

11.5.
Zapping Procedure. To apply a zap, perform the following steps:
  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.


11.6.
NEWDOS/80 Zap Distribution.

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.


11.7.
Initial Installation of Zaps.

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.


11.8.
Subsequent Installation of 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.


11.9.
Diskette Update Service.

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.


11.10.
Zap Duplication.

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.


12. CONVERSION INFORMATION AND MISCELLANEOUS COMMENTS.

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.

12.1.
RBAs gain in respectability.

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.


12.2.
Converting from Version 1 to Version 2 on the Model I.
  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.

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

  1. DEBUG can no longer be enabled/disabled by the value in 4315H. User programs can continue to set this location, but DOS ignores it.
  2. DEBUG can no longer be entered by pressing the BREAK key; only the 123 keys are used (see section 4.1).
  3. 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.

  1. 5 inch double density diskettes are supported in Version 2 for the PERCOM and LNW double density modifications.
  2. 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.

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

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


12.3.
Converting from Version 1 on the Model I to Version 2 on the Model III.
  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.

12.4.
NEWDOS/80 Version 2 incompatibilities with Model I TRSDOS Version 2.3.
  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


12.5.
NEWDOS/80 Version 2 incompatibilities with Model III TRSDOS Version 1.3.
  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.

12.6.
Miscellaneous Comments.
  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.

APPENDIX A

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.

FP
Value Meaning
(null)
If the file is an MU, MF or FF type file, and the REMRA is valid, the file is advanced to the next sequential record; in any other case, the current file position is not changed and processing continues from the position left at the termination of data transfer of the previous GET/PUT. Open leaves REMRA marked invalid for all file types, and sets current file position equal to fd (except for mode “E”, which causes current file position to be set equal to the FPDE’s EOF value). The first sequential access for record segmented files always starts at current file position.
*
The current file position is not changed, This specification allows the continuation of processing of a particular record by a GET or PUT. It is primarily used to continue processing a record already partially read or written, For MU, MF and FF type files, it cannot be used to advance the file to the next sequential record, even though the file is actually already positioned at that record, having exhausted the bytes of the current record. To sequentially advance to the next record, use fp = (null)
#
If the REMRA is valid, the file is positioned to process that record again; an error condition is raised if the REMBA is invalid. For MU, MF and FF type files, this specification allows the reprocessing of the record currently being processed, from the beginning, perhaps with different variable names or expressions in the IGELs. For MI and FI type files, it allows the reproceseing of the same data item group as was processed by the immediately preceeding GET/PUT,
$
If the REMBA is valid, the file is positioned to begin processing at again it the point where the previous GET or PUT was at the end of its file positioning phase; an error condition is raised if the REMBA is invalid. This specification allows the reprocessing of a particular group of data by a GET/PUT, and is primarily used to reposition a file for partial-record I/O, It functions in the same fashion for all NEWDOS/80 file types.
%
This specification performs a “pseudo FIELD” operation. No data transfer takes place; the filearea FCB is not changed; the file does not have to be open when this fp is used. It is used with FF and FI files to allocate user data strings of fired sizes from the BASIC string storage area in high memory.
&
This specification is used only with PUTS, and has no effect on file positioning. It does however cause the current contents of a filearea buffer to be written to the diskette. It should be used whenever the data in the buffer is particularly sensitive. It may be used specifying the FAN of a PRINT file.
&&
This specification is similar to &, except that in addition the file’ s EOF is updated from the FCB to the FPDE. PUT fan,&& allows the programmer to force the EOF update to the FPDE without having to do a CLOSE.
!rba
Using this form of fp specification causes GET/PUT processing to begin at the specified location in the file where rba is a BASIC expression evaluating to a RBA value. . For MU, MF and FF type files, the system checks to make sure that a record begins at the specified location. In the case of a MU file, the RBA value must point to an SOR item. This form of fp specification demands the greatest amount of care and premeditation on the programmer’s part, as if it is used incorrectly, especially with FF and FI type files, it can be most disastrous. It is just about the only way to randomly access data stored in MI, MU end FI type files.
!%
This specification is basically the same as the !rba form except that the current EOF value is used as the RBA. It is commonly used to position a file for extension – that is, to add records/data to the end of the file. To extend a file it must be opened with mode “R”; mode “D” will yield an error if extension is attempted.
!$rba
This specification allows the programer to position the file for the next data transfer for that particular filearea, without regard to the specific access technique or verb used for the transfer; no data transfer to user data areas occurs with this specification. No IGEL may be referred to or included in the GET/PUT using this specification. The positioning resulting from the use of this specification doesn’t become effective until the next INPUT/PRINT or GET/PUT, and then only if no additional positioning is specified. It can be used to position a file for random access in a program which uses a subroutine containing a single GET/PUT having a (null) fp to do all file access; such a program could process sequential groups of records randomly distributed throughout a file.
!$%
The basic function of this specification is identical to !$rba, except that it uses the current EOF value as the RBA. The GET/PUT using this specification must not refer to or include an IGEL. Again, the file position resulting from this specification doesn’t take effect until the next INPUT/PRINT operation, or the next GET/PUT (if another fp isn’t specified).
!#rba
Used only with PUT, this specification sets the filearea’e EOF value equal to the value rba, For the real EOF value of the file to be altered, that is, the one in the FPDE, the filearea must either be closed or a PUT && statement executed. The EOF value provided must be rational for the file type involved. For MF and FF files it must be an integral multiple of the file’s standard record length.
rn (Record Number)
This specification is the same as the one supported by TRSDOS; rn is a numeric BASIC expression which evaluates to an integer value from 1 to 32767, inclusive. The specified record number is converted to an RBA which is then used in the same functional manner as !rba.

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.

APPENDIX B

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 END
40 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.

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.

*** APPENDIX B CONTINUES ….


Navigation

Go back to …

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

Leave a Reply

Your email address will not be published. Required fields are marked *