Radio Shack Hardware Manual 3 Disk System Owners 1980 Tandy A Text

User Manual: manual pdf -FilePursuit

Open the PDF directly: View PDF .
Page Count: 182 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Disk System Owner's Manual

Mini-Disk Operation

TRSDOS™ Disk Operating System

Disk BASIC Programming Language

.*<-?-' *>t vv\

".*

The biggest name in little computers1

CUSTOM MANUFACTURED IN THE USA BY RADIO SHACK CADIVISION OF TANDY CORPORATION

This equipment generates and uses radio frequency energy. If not installed and used prop-

erly, that is, in strict accordance with the manufacturer's instructions, it may cause interfer-

ence to radio and television reception.

It has been type tested and found to comply with the limits for a Class Bcomputing

device in accordance with the specifications in Subpart Jof Part 15 of FCC Rules, which are

designed to provide reasonable protection against such interference in aresidential instal-

lation. However, there is no guarantee that interference will not occur in aparticular

installation.

If this equipment does cause interference to radio or television reception, which can be

determined by turning the equipment off and on, the user is encouraged to try to correct the

interference by one or more of the following measures:

•Reorient the receiving antenna

•Relocate the computer with respect to the receiver

•Move the computer away from the receiver

•Plug the computer into adifferent outlet so that computer and receiver are on different

branch circuits.

If necessary, you should consult the dealer or an experienced radio/television technician for

additional suggestions. You may find the following booklet prepared by the Federal Com-

munications Commission helpful: How to Identify and Resolve Radio-TV Interference

Problems.

This booklet is available from the US Government Printing Office, Washington, DC

20402, Stock No. 004-000-00345-4.

This equipment has been certified to comply with the limits for aClass Bcomputing device,

pursuant to Subpart Jof Part 15 of FCC Rules. Only peripherals (computer input/output

devices, terminals, printers, etc.) certified to comply with the Class Blimits may be attached

to this computer. Operation with non-certified peripherals is likely to result in interference to

radio and TV reception.

CHANGE OF ADDRESS

NOTE: if you move, please fill out this card and return it so that you may continue to

receive information regarding this program. «AfirrtlQl

Purchase Date

NEW ADDRESS:

Name

Company

Address _

City

State Zip

Cat. No.

OLD ADDRESS:

Name -

*JRon?a/63

Company .

Address _

City

State

Zip

INSTRUCTIONS FOR USE

1. Register one software package per card only.

2. Complete the Software Registration portion of this form and mail it immediately.

The Catalog No. may be found by examining the upper-right corner of your diskette.

3. For convenience achange of address card has been included. Copy all information

from the Registration Card onto it prior to sending the Registration Card.

Model III Users

XFERSYS UTILITY ON TRSDOS 1.3

The Model III diskette in this package contains aNEW

version of TRSDOS which is not compatible with OLD versions

of TRSDOS.

OLD TRSDOS diskettes to be used under the NEW TRSDOS MUST

be XFERSYSed before use. Once XFERSYSed, an OLD TRSDOS

diskette becomes aNEW TRSDOS diskette and should not be

used with OLD TRSDOS again. If you started with an OLD

system or data diskette, the XFERSYSed diskette will be a

NEW system or data diskette respectively.

OLD diskettes used under NEW TRSDOS without XFERSYSing, may

cause extraneous information to be read at the end of

files, giving afalse End-of-File (EOF) indication. Some

programs will not function properly under these conditions.

NEW diskettes used under OLD TRSDOS, may not access all

data and/or NEW programs may not run correctly.

If you need to use the XFERSYS utility, see the TRSDOS

section of your TRS-80 Model III Disk System Owner's

Manual

Note: When changing from one TRSDOS to the other, you MUST

press the RESET button each time the diskette in

Drive is changed. You may also XFERSYS onto aNEW

data disk. If this is done, all system files of the

system diskette will be moved onto the data diskette.

RADIO SHACK APPLICATION PROGRAMS WHICH WERE DELIVERED ON AN

OLD TRSDOS DISKETTE SHOULD NOT BE XFERSYSed.

OLD: TRSDOS 1.1 and 1.2.

NEW; TRSDOS 1.3

file: Acollection of information stored as one

named unit in the directory,

program: Afile which causes the computer to

perform afunction,

data: Information contained in afile which is

used by aprogram,

system diskette: Adiskette containing TRSDOS. When this

diskette is placed in Drive and the

RESET button is pressed, TRSDOS will begin

to run.

data diskette: Adiskette which does not contain TRSDOS.

If this diskette is placed in Drive and

RESET is pressed, the screen will clear

and "Not aSYSTEM Disk" will be displayed.

XFERSYS: Aprogram contained on the TRSDOS 1.3

diskette.

8759117-681

Tips CnLoad og Disk basic

There are several ways, other than those described in the manual, to start up Disk basic.

basic program -F.files -m: address

program is atrsdos file specification for aDisk basic program. After start-up, Disk basic will run the

program. This is optional.

F.files fells Disk basic the maximum number of files that may be open at one time, diesis a

number from So 15. This is optional; if omitted, 3is used. If Variable length files are

needed, you must include the suffix vafter files; otherwise, files will be Fixed length.

-w.address tells Disk basic not to use memory above the specified address. This is optional; if

omitted, Disk basic uses all memory up to Top.

If all options are omitted, Disk basic will prompt with HOW MANY FILES? and memory?

The options allow you to specify any or all of the following:

•Aprogram to run after Disk basic is started.

•The maximum number of data files that may be Open at one time. The larger the number of files,

the less area available for storing and executing your programs. (Note: Each Fixed length file takes

up 360 bytes and each Variable length file takes up 616 bytes of memory.)

•The highest address to be used by Disk basic during program execution. Omit this unless you are

going to call machine-language subroutines.

Under trsdos ready, if you type:

BAS IC(ENTER) ,Disk basic will enter the command mode once you answer the files and

memory prompts.

BASIC -Fs1fEMTEff ,Disk basic will Open one fixed length file and protect no memory.

BASIC -M: 32000 (ENTER) ,Disk basic will Open three fixed length files and will use

memory no higher than 32000.

BASIC PAYROLL -F:3>' (ENTER). Disk basic will start-up. then load and run the basic

program called payroll; three variable length files can be Opened, and basic can use all

available memory.

Note: If you PATCH Disk basic to prompt you for cassette speed when you enter Disk basic, you

will still be prompted with CASS? no matter which option you use.

Important Note for Model III trsdos 1.3 Users!

The 1.3 version of trsdos will return with ERROR 31 (PROGRAM NOT FOUND) when you

attempt to use the ROUTE command.

Thank-You!

IADivision of Tandy Corporation

8759109

_^_ _®

rpie-eQ

r,. :"ir

Dfek

Omfnerse

ipytofiuia!

;ADIVISION OF TANDY CORPORATION

FORT WORTH, TEXAS 76102

TRS-80 Mode! Ill Disk System Owner's Man-

Reproduction or use, without express written per-

mission from Tandy Corporation or any portion of

this manual is prohibited. While reasonable

efforts have been taken in the preparation of this

manual to assure its accuracy, Tandy Corporation

assumes no liability resulting from any errors or

omissions in this manual or from the use of the

information obtained herein.

Model III TRSDOS® Operating System:

The system software in the Model III microcom-

puter is retained in aread-only memory (ROM)

format. All portions of this system software,

whether in the ROM format or other source code

form format, and the ROM circuitry are copy-

righted and are the proprietary and trade secret

information of Tandy Corporation and Microsoft.

Use, reproductions, or publication of any portion

of this material without the prior written authori-

zation by Tandy Corporation is strictly prohibited.

10 987654321

.-., .OWNER'S MAMUAL

Congratulations on your purchase of the Model III Disk System. We think it's a

valuable tool which will save you work as well as give you hours of enjoyment

(or maybe both at once). You'll have all the power of the non-disk Model II!,

plus the following features:

•Your Computer can now be controlled by trsdos®, the powerful trs-so Disk

Operating System, trsdos is included on adiskette with the Disk System.

•Using trsdos, you can run awide variety of programs, such as the Disk basic

interpreter included on the trsdos diskette.

•Each "system" diskette has approximately 126,720 bytes of storage available

for your own programs and data; each "data" diskette has 178,944 bytes

available.

•You can load and save data at the approximate rate of 250,000 bits per second.

•Your system can continue to grow in power and convenience. When Radio

Shack issues improvements and enhancements to the system programs, you

can "install" them simply by obtaining anew release of the trsdos diskette.

Publications related to the use of the Model III Disk System:

1. Model III Disk System Owner'sManual (this manual). We'll call it the "Disk

Manual" for short.

2. Model III Disk System Quick Reference Card.

3. Model 111 Operation and basic Language Reference Manual, the "Model III

Manual" for short.

4. Model HI basic Quick Reference Card.

For Disk Operation:

This Disk Manual supplements the Model III Manual. Use the Disk Manual as

the primary source of information; we'll tell you when to refer to the non-disk

Model III Manual.

For Non-Disk Operation:

To use the Computer as anon-disk system, all you need is the Model III

Manual.

For Programming Information:

The Model III Manual contains most of the programming information, except

that which pertains to disk input/output. In this manual, we will assume that you

TRS-80 MODEL ill DISK SYSTEM

are familiar with the basic programming definitions and details given in the

Model III Manual.

The Model III Disk System is intended for use by novices as well as

experienced computer operators and programmers. In designing and writing this

Disk Manual, we've tried to define and satisfy the needs of both groups:

•Novices who might prefer a sequential presentation which emphasizes

procedures and explains the purpose of various features.

•Experienced users who might prefer amore analytical presentation which

makes it easy to find specific information.

In this manual, you'll find information that should satisfy your needs, whichever

group you might belong to.

The "Sample Sessions" are especially geared for novices, while the Technical

Information chapters are for the more experienced users.

Keep in mind, however, that it isn't necessary to read the entire manual to

operate the Disk System. If you are only interested in Disk basic, for example,

read the Operation section of this book and then turn directly to the Disk basic

section. You can then go back to the trsdos section when you need to.

Special Terms

Even in the non-technical sections of this manual, we've had to use numerous

special terms. Rather than scattering and repeating definitions throughout the

book, we have used the following convention which we hope you'll find

helpful.

Special terms which are fully defined in another part of the manual are printed in

boldface. Look up the word or phrase in the Index; this will tell you where the

word is fully defined.

mSBBBBBB^E

*0- 'R'S MAN!

'V-'J,

saa

Contents

Operation

Installation ............:„.,„..,.....„...„ 1

Operation ...................,,......,.....,,,...,,....,,,..,,. 4

Diskettes ....................................................... 5

nDescription fj Care

System Start-Up 6

Important Disk Operations 8

backup format QModel 1/III Conversion

Disk basic 1

Quick instructions Start-Up Loading Baud Rate

Troubleshooting and Maintenance 13

Notation and Abbreviations ....................................... 14

Specifications 1

TRSDOS

Description of trsdos 17

Roles basic ram Use QMemory Map

Using trsdos 20

Commands 20

nEntering Syntax Forms

File Specification .............................................. 22

File Name ................................................. ..,23

Drive Specification 23

Password 24

AFew Important Definitions 24

Library Commands ............................................. 26

Utility Commands 67

Technical Information 74

Disk Organization File Structure Systems Routines (I/O)

trsdos Error Codes/Messages 90

TRS-80 MODEL ill DISK SYSTEM

Disk BASIC

Introduction 91

Enhancements to Model III Disk basic 93

Q] Abbreviations fj Commands

Disk-Related Features 116

File Manipulation File Access

Methods of File Access 145

Q] Sequential QRandom

Disk basic Error Codes/Messages 155

Index 157

Customer Information 160

Warranty ........................... .......... Back Cover

•v

*V*mmt

*•%»*»,-»•

if"!

"ERATH

mmm ON LJli

First set up the Computer according to the instructions in the Model III Manual.

If you have aone- or two-drive system, installation is now complete. The built-

in drives should be ready for use.

If you have athree- or four-drive system, you need to connect the external

drives.

External Disk iirives

The two external drives are not interchangeable. They have different Radio

Shack Catalog Numbers and afew internal differences.

First External Drive Purchased

(Includes Cable)

Second External Drive Purchased

System

Name

'Drive 2/3'

'Drive 2"

Catalog

Number

26-1164

26-1161

The 26-1 164 drive may be used as Drive 2or 3, depending on the number of

drives in the system. In a three-drive system, it is always Drive 2(the last

drive). In afour-drive system, it is always Drive 3(again, the last drive).

The 26-1 161 drive may only be used in a four-drive system, in which it must be

Drive 2.

Locate the flat "ribbon" cable that was included with the 26-1 164 drive.

Notice that it has asingle plug on one end, and two plugs clustered at the

other end. See Figure 1for plug labels.

2. Connect the solitary "Computer" plug to the Disk Expansion Jack on the

bottom rear of the Computer. See Figure 2.

3. Now refer to Figure 3. Connect the external drive(s) to the other end of the

cable, as follows:

3-A. If you have one external drive (26-1 164):

Connect it to the "Drive 2" plug near the middle of the ribbon cable.

3-B. If you have two external drives (26-1 164 and 26-1 161):

Connect the 26-1 164 to the "Drive 3" plug on the end of the cable.

Connect the 26-1 161 to the "Drive 2" plug near the middle of the cable.

4. Plug the external drive(s) into an appropriate source of AC power. Power

requirements are specified on the unit and in the specifications given in this

manual.

You are now ready to start the Disk System.

IIP

iiH

§£3

I..'SB IODEL ill DISK SYSTEM JMW^

Computer Plug

Drive 3Plug

Figure 1. External Disk Cable with Plugs Labeled.

Figure 2. Connection of the External Disk Cable to the Model

Attach the plug so the cable exits

toward the rear of the Computer.

EDGE CARD PLUGS GUIDE PIN GUIDE SLOT

Figure 3. Connection of external disk drives.

IiliiilK WSSSM KM

Operation

First, take a few minutes to become familiar with the various elements of your

Disk System. Refer to Figures 4and 5. This is very important. If you try to use

the Computer without having alittle background information, you could damage

adiskette.

Figure 4. The Model III Disk System with External Drives (optional/extra).

©Drive 0. The trsdos "system diskette" goes

in this drive.

©Drives 1, 2, and 3. These drives may

contain "data diskettes." Data diskettes are

described briefly in this chapter.

©Drive Select led. When adrive is being

accessed, its led lights up.

©Drive Door. To insert or remove adiskette,

open this door. Never remove adiskette

while the led is lit, or while the diskette

cohtains open files.

©Reset Button. When you press this button,

the Computer will attempt to load the

operating system software from Drive 0. The

trsdos diskette should be in Drive when

you press this button.

©Power Switch. All drives should be empty

when you turn the Computer on or off.

Otherwise, the information on the diskettes

could be destroyed.

mniB&m

yPtHAISOl'

*sp¥wlrl£

©. ©

Figure 5. ADiskette. (Catalog Number 26-305, 26-405, or 26-406)

©Storage Envelope. While adiskette is not in

use, keep it here.

©Write Protect Notch. When this is covered,

the disk-drives cannot write (change infor-

mation) on the diskette. Do not pinch the tab

into the notch when you apply it. If the tab

becomes indented, the disk drive may not

sense that the disk is write-protected. Leave

the notch uncovered if you want to save or

change information on the diskette.

©Jacket. The diskette is permanently sealed

inside this protective jacket. Do not attempt

to remove it.

©Read/Write Window. The disk drive

accesses the diskette surface through this

window. Don't touch the diskette surface.

©Label. To write on this label, use only afelt-

tipped pen. Any other writing implement

might damage the diskette.

Diskettes

In general, handle diskettes carefully, using the same precautions you use with

tape cassettes and high-fidelity records. Asmall indentation, dust particle, or

scratch can render all or part of adiskette unreadable

—

permanently.

'Keep the diskette in its storage envelope whenever it is not in one of the

drives.

•Do not place adiskette in the drive while you are turning the system on or off.

•Keep diskettes away from magnetic fields (transformers, ac motors, magnets,

tvs, radios, etc.). Strong magnetic fields will erase data stored on adiskette.

a^4<HBH

•Handle diskettes by the jacket only. Do not touch any of the exposed surfaces.

Don't try to wipe or clean the diskette surface; it scratches easily.

•Keep diskettes out of direct sunlight and away from heat.

•Avoid contamination of diskettes with cigarette ashes, dust or other particles.

•Do not write directly on the diskette jacket with ahard point device such as a

ball point pen or lead pencil; use afelt tip pen only.

•Store diskettes in avertical file folder on ashelf where they are protected from

pressure to their sides (just as phono records are stored).

•In very dusty environments, you may need to provide filtered air to the

computer room.

Tips on Labeling Diskettes

Each diskette has apermanent label on its jacket. This label is for "vital

statistics" that will never change. For example, to help keep track of diskettes,

it's agood idea to assign aunique number to each diskette. Write such anumber

on the permanent label. You might also put your name on the diskette, and

record the date when the diskette was first put into use. Remember, use only a

felt tip pen for marking.

This "permanent" label is not agood place to record the contents of the diskette

since that will change, and you don't want to be erasing or scratching out

information from this label.

1. Turn all peripherals on.

2. Turn the Computer on. Wait until all disk drive motors stop.

3. Locate the trsdos diskette that was supplied with the Disk System. Insert it

into Drive 0, with the label side facing up and the read/write window

pointing into the drive slot. See Figure 6.

4. When the diskette is fully inserted, close the drive door.

5. Press reset. The Computer should now load trsdos and begin the start-up

dialog described in the next section.

If nothing happens on the Display, or if the message: DISKETTE? or NOT A

SYSTEM DISK is displayed, check the following:

•Are you using atrsdos "system" diskette?

•Is the diskette properly inserted into Drive 0?

•If external drives are present, are they properly connected and turned on?

mmi

OPERATiO!

Ifc

Figure 6. Inserting aDiskette.

If you can't find the problem, refer to the Troubleshooting and Maintenance

chapter for further suggestions.

TRSDOS Start-Up Dialog

Whenever you reset the Model III Disk System, it loads trsdos and begins the

start-up dialog.

The trsdos version number and date of creation will be displayed, followed

by the amount of ram 02K or 4SK) and the number of drives in the system.

2. trsdos will prompt you to enter the date in the form mm/dd/yy. For example,

07/04/80 for July 4, 1980. Type in the correct date and press CENTER) ,trsdos

will not continue until you type in the date correctly.

3. trsdos will prompt you to enter the time in 24-hour form hh:MM:SS. For

example, 14:45:00 for 2:45 p.m. Type in the correct time and press (ENTER). If

you don't wish to set the time, simply press CENTER) at the beginning of the

line, trsdos will set the time to 00:00:00.

4. trsdos will now display the message, TRSDOS READY

Whenever this is displayed, you are in the trsdos ready mode, and you may

type in atrsdos command.

Important Disk Operations

In this section we will describe three very important operations:

Duplicating the trsdos diskette (backup)

2. Initializing adata diskette (format)

3. Converting files from Model Ito Model III trsdos (convert).

All new customers should complete the trsdos backup procedure now; multi-

drive customers should also complete the format operation for a few diskettes.

Detailed information is provided later in this manual; here we will simply

outline the procedures.

Making aBACKUP (Duplicate) of TRSDOS

Your first operation should be to duplicate the trsdos diskette you received

from Radio Shack. The trsdos diskette contains autility program called

backup to accomplish this.

Locate the trsdos diskette and anew, blank diskette. The trsdos diskette

will be referred to as the "source," while the blank one will be called the

"destination," during backup.

2. Start trsdos as explained in the previous section. TRSDOS READY should be

displayed.

3. Type: BACKUP (INTER)

4. trsdos will now load and start backup. It will ask you:

SOURCE DRIVE NUMBER?

Specify the drive which contains the original trsdos diskette by typing:

(ENTER)

5. Next TRSDOS will ask: DESTINATION DRIVE NUMBER?

Now specify the drive which will be used for making the duplicate trsdos. If

you have two or more drives in your system, type: 1(ENTER)

6. TRSDOS will ask: SOURCE DISK MASTER PASSWORD?

Type: PASSWORD (ENTER)

(password is the password of the supplied diskette.)

Now' the duplication process will begin.

If the destination diskette is not formatted, backup will format it before

continuing. (Before any diskette can be used, it must be initialized or

"formatted" —the data regions defined and labeled, and atable of contents

or "directory" created.)

If you are using asingle-drive system, trsdos will prompt you to swap

source and destination diskettes several times during the formatting/backup

process.

After a single-drive backup, trsdos will display the message:

INSERT SYSTEM DISKETTE CENTER)

Be sure you have atrsdos diskette in Drive 0, then press (ENTER) .

The duplication process is now complete. We suggest you save the original

trsdos and use the duplicate as your working copy. If anything happens to the

working copy, you can make another one from the original.

aking aData Diskette (FORMAT)

This section applies to multi-drive systems only.

Drive must always contain atrsdos diskette, so the Computer can have

access to the system programs stored there. Much of the storage capacity of this

diskette is taken up by the system programs.

However, the other drives in the system may contain "data" diskettes which

have no system programs. All of the storage capacity of such diskettes is

available for your programs and data.

The format utility program takes adiskette and initializes or "formats" it.

If the diskette was previously formatted, all prior information can be lost.

The resultant diskette contains no system files and may only be used in

Drive 1, 2or 3.

In the trsdos ready mode, type: FORMAT (ENTER)

2. trsdos will start the formatter program and ask you aseries of questions:

FORMAT WHICH DRIVE?

Insert ablank diskette into Drive 1.Type: 1(EMTER)

DISKETTE NAME?

This name will serve as an internal label for the diskette. Type in any

appropriate name of one to eight letters and numbers, starting with aletter.

Press CENTER) at the end of the name.

MASTER PASSWORD?

The password may be from one to eight letters and numbers, starting with a

letter. Press (ENTER) at the end of the password.

Use of the password allows backup, prot, and purge access to all non-

system files. Unless special protection is needed, we suggest you use the

password password. Whatever password you select, don't forget it!

TF1S-80 MODEL 111 DISK SYSTEi

»1 WSXSSSSKBS^SBK^SBKSSKKMSSI^KB^SS^B^SS

If the diskette contains data, trsdos will warn you:

DISKETTE CONTAINS DATA. USE DISK OR NOT?

The warning is needed since format erases all previous information from the

diskette. Type N(ENTER) to cancel format; type Y(ENTER) or U(ENTER) to

continue it.

3. trsdos will now format and verify the diskette. The data diskette will then

be ready for use in Drive 1, 2, or 3.

Model I/III Conversion (CONVERT)

In general, Model Itrsdos diskettes cannot be used in aModel III Disk

System. However, Model III trsdos includes aspecial program, convert, to

read aModel Itrsdos diskette and copy its non-system files onto aModel III

trsdos diskette.

In two-drive systems, the files must be copied onto aModel III system diskette;

in three- or four-drive systems, the files may be copied onto adata diskette.

Here are abbreviated instructions for using this program. For further details, see

CONVERT.

Using aModel IDisk System, remove all passwords from the diskette to be

converted. You can do this with the prot command, described in the Model I

TRSDOS/Disk basic Owner's Manual.

2. Start Model III trsdos.

3. Place the Model Idiskette in Drive 1,2or 3. (In two-drive systems, use

Drive 1; in three- or four-drive systems, Drive 2.)

4. In three- or four-drive systems, place aModel III data diskette in Drive 1

5. Type: CONVERT (ENTER)

4. The conversion program will start by asking for the source drive number.

Type in the number of the drive containing the Model Idiskette, then press

dNTM).

5. Next, the conversion program will ask for the destination drive number. Type

in the number of the drive containing the Model III diskette, then press

(ENTER) .(In two-drive systems, use Drive 0; in three- or four-drive systems.

Drivel.)

6. Now all the non-system files will be converted and copied onto the

destination diskette. As each file is copied, its name will be displayed.

7. When the process is completed, you may remove the Model Idiskette. It is

unchanged by the convert program. The destination diskette contains the

converted files.

8. To restore password protection to the converted files, you may use the prot

or attrib command.

Quick Instructions for Using Disk BASIC

in this section we'll "walk you" through the following procedures:

Starting Disk basic

2. Running asimple program

3. Saving aprogram in adisk file

4. Loading aprogram from adisk file

For programming information, see the Disk basic section of this manual.

Here we are showing procedures only.

Starting Disk BASIC

Under trsdos ready, type: BASIC (ENTER)

The Computer will load and start basic. First, it will ask two questions.

Press (ENTER) in response to each of them.

HOW MANY FILES? (INTER)

MEMORY SIZE? (EMTER)

Aheading will be displayed, followed by:

READY

You may now begin using Disk basic.

Saving aProgram

You should have aprogram in memory, and be in Basic's ready mode. Type:

SAVE "PROGRAM" CENTER)

basic should now save the program in adisk file we arbitrarily named

"program." Any other suitable file name would do.

Loading aProgram

For this sample session, we will load the program just saved.

First type: NEW CENTER) to erase it from memory. (This is to prove that it can be

retrieved from the disk file.)

HEW66t

TRS-80 MODEL 111 DISK SYSTEI

Now type: LOAD "PROGRAM" (ENTER)and basic will load the specified

program.

You may now list it and run it.

For further information on using Disk basic, see Section 3of this manual.

Setting the Cassette Baud Rate under Disk

trsdos sets the cassette baud rate to High. If you would like to change this, use

the following trsdos command:

PATCH BASIC/CMD (ADD =5202 >FIND =00 >CHG =FF i(ENTER)

Consequently, you will be prompted with: CASS? whenever you start Disk

basic.

You may then type either H (High) or L(Low) to choose the rate you need.

To change the system diskette back to its original state (i.e., no CASS?), simply

use the trsdos patch command again but reverse the find and chg values.

OPERATION j

Troubleshooting and Maintenance

If you have problems operating your Model III Disk System, please check the

following symptoms and cures, and check the corresponding table in your

Model III Manual.

If you can't solve the problem, take the unit to your local Radio Shack. We'll

have it fixed and returned to you as soon as possible.

Symptom Cure

Disk drive motors run

continuously when the Computer

is turned on.

Check external drive connection sequence.

Drive 26-1 164 must always be the last

external drive.

Computer will not load trsdos. 1

Make sure you have inserted the

trsdos diskette properly in Drive 0.

2. Make sure all peripherals are properly

connected.

Error Messages Look up the message in the trsdos or

basic Error Message Section. The "cure"

should be listed.

Frequent disk i/o errors 1

Diskette is partially erased. Backup the

diskette, then re-format it.

2. Diskette is worn out. Use backup copy, if

available, to make anew working copy.

3. Disk drives need cleaning or alignment

by Radio Shack service technicians.

Maintenance

For reliable operation, the disk drives must be kept clean and properly aligned.

These procedures should be done by Radio Shack service technicians, according

to the following schedule:

Degree of Use

Commercial data processing

environment

Occasional home use

Maintenance Interval

Every month for medium use.

Every 8-10 months; more often if

needed.

For further instructions, see the Troubleshooting and Maintenance section in

your Model III Manual.

For the sake of clarity and brevity, we've used some special notation and type

styles in this book.

capitals and punctuation

indicate material which must be entered exactly as it appears. (The only

punctuation symbols not entered are ellipses, explained below.) For example,

in the line:

DUMP LISTER (START =7000, END =7100JRA =7004)

every letter and character should be typed as indicated.

lowercase italics

represent words, letters, characters or values you supply from aset of acceptable

values for aparticular command. For example, the line:

LIST filename

indicates that you can supply any valid file specification after list.

Ellipsis indicates that the preceding items can be repeated. For example:

ATTRIB filename (option, ...)

indicates that several options may be repeated inside the parentheses.

This special symbol is used occasionally to indicate ablank-space character

(ASCII code 32 decimal, 20 hexadecimal).

PRINT "HHHIH!"

X'««««'

Indicates that nnnn is ahexadecimal number. All other numbers in the text

of this book are in decimal form, unless otherwise noted.

X'7000'

indicates the hexadecimal value 7000 (decimal 28672).

COMPUTER TYPE

Any words, letters, or numbers that are displayed on the screen will be in

computer type (dot-matrix). Uppercase letters are used; however, your screen at

times may display lowercase letters instead.

OPERATION J

Specifications

Diskettes

Diskette Organization

(Formatted Diskette)

Operating Temperature

Power Requirements

(External Drives)

A" mini-diskettes

Radio Shack Catalog

Number 26-305,

26-405 (package of three),

or 26-406 (package of 10)

Single-sided

Double-density

40 Tracks

18 Sectors/Track

256 Bytes/Sector

55 to 80 Degrees Fahrenheit

13 to 27 Degrees Celsius

120 VAC, 60 Hz, 28 VA (240 VAC, 50

Hz, Australian; 220 VAC, 50 Hz,

European)

^tnn

5=3=3 E=2S

"WiliilS

Sifts

ISDQS

Description of TRSDOS

What Is TRSDOS?

trsdos (pronounced "triss-doss") stands for "trs-80 Disk Operating System."

It fulfills three roles:

Master Program

2. Command Interpreter

3. Program Manager

As the master program, trsdos enables the microprocessor and its various

components to interact efficiently. The components include:

•Random Access Memory (ram), trsdos reserves space for its own needs and

allocates space for user programs.

6Disk Drives, trsdos interfaces with the disk hardware and provides afile

system for storing system and user data on diskettes.

eInput/output devices. These include the keyboard, video display, printer, and

rs-232-c equipment.

trsdos is also a command interpreter. Whenever it displays TRSDOS READY,

you may enter commands that control how the system works. These are known

as "library" commands.

In its role as program manager, trsdos will load and run system or user

programs. During this time, the system or user program is in control of the

Computer.

Figure 7illustrates the relationships between these three roles.

here Does BASIC Fit ta?

Referring to Figure 7, you'll see that Disk basic falls under the "language

package" category.

Disk basic consists of some general enhancements to Model III basic, plus the

disk input/output capability. It uses Model III basic (stored in rom) whenever

possible. For instance, the Model III basic rom includes all of the mathematical

functions.

If you're used to the non-disk system, there's one difference you should

understand from the beginning: In the non-disk system, basic is in control when

you start-up. In the disk system, however, trsdos is in control when you start-

up. You have to tell trsdos to load and run basic. Only then can you begin

running aprogram written in basic.

L_.

1§

.J"

iiSii

TRS-8C ISK SYSTEM

MMlMiiMiMi

trsdos is stored on the system diskette included with your Disk System. Each

time the Computer is turned on or reset, the trsdos master program is loaded

into ram so it can take charge.

trsdos occupies approximately 40,000 bytes of space on the diskette; however,

only aportion of that is in ram at once. This is possible because trsdos is

divided into several independent "modules."

The "resident" module is in memory at all times. It consists of input/output

drivers, tables, the command interpreter, and other essential routines.

Additional modules are loaded as needed, and replaced (or "overlaid") by other

modules when they are no longer needed.

Note: After you enter alibrary or utility command, you will usually hear

trsdos accessing the system disk. It is loading an overlay module which

contains the code necessary to complete the command.

The Memory Map in Figure 8illustrates how trsdos utilizes the available

memory space.

Command

Interpreter

laster Program

System Utility

Programs (FORMAT,

BACKUP, etc.)

Figure 7. trsdos Roles.

Program Manager

Language packages

(Disk BASIC,

Editor/Assembler,

etc.)

Z-80

User

Programs

BASIC,

OTHER

PROGRAMS

4000H »fe3#4-

5200H *°" z

5500H '

Zil<o0

DOS OVERLAYS

7000H iwi-

FORMAT

8000H 327fc

END-180H" -~-

'& fff H-l ;

3«+

Figure 8. trsdos Memory Map

(32K) (48K)

END (BFFFH) (FFFFH)

SBM

TRS-80 MODEL HI DISK SYSTEM

Using TRSDOS

Entering aCommand

Whenever the trsdos prompt.

TRSDOS READY

is displayed, you can type in acommand, which can be no more than 63

characters in length. You must press (ENTER) to end the line, trsdos will then

"accept" the command.

For example, type: CLS (ENTER) trsdos will clear the Display and the trsdos

ready prompt will reappear.

In general, your commands will require more than one word. For example, to

kill (delete) afile named myname, you have to specify the command and the

filename.

KILL MYNAME (ENTER)

tells trsdos to find the file named myname, eliminate it from the diskette, and

release the space previously occupied by that file.

Whenever you type in aline, trsdos follows this procedure:

1. First it checks to see if what you've typed is the name of atrsdos command.

If it is, trsdos executes it immediately.

2. If what you typed is not atrsdos command, then trsdos will check to see if

it's the name of aprogram file on one of the drives.

3. When searching for afile, trsdos looks first through Drive 0, then Drive 1,

etc., unless you include an particular drive specification with the file name

—or specify the master command (see Library Commands).

If trsdos finds aspecified user file, it will load and execute the file if it is a

program file. Otherwise, you'll get an error message.

Command Syntax

Command syntax is acommand's general form (like the grammar or structure of

an English sentence). The syntax tells how to use keywords (such as dir, list,

create, etc.) together with the necessary parameters and punctuation.

If you need help remembering the syntax form of aspecific command while

you're operating trsdos, type in:

HELP command (ENTER)

command should be the specific Library Command you're having trouble with.

TRSDOS will give you the syntax format as well as a brief definition of the

command.

Commands (Syntax Forms)

No-file commands

command (options) comment

options is alist one or more parameters that may be needed by the

command. Some commands have no options. The parentheses

around options must he included unless the option itself is

omitted.

comment is an optional field used to document the purpose of the

command. Comments are useful inside automatic command

input fifes (see bu!ld and do).

One-file commands

mmat ITil m•'op\ on l'j <me if

filesm nrsst nal; 7o.ilk spec ica ii n

Of, ions- See defin U1above

comment— See definition above.

\JH TRS^BO MODEL B18 DIS KSYSTEM

Two-file commands

command filename delimiter filename (options) comment

filename is astandard trsdos file specification.

delimiter is ablank space.

options —See definition above.

comment—See definition above.

File Specification

The only way to store information on adiskette is to put it in adisk file.

Afterwards, that information can be retrieved via the file name you gave the file

when you created or renamed it.

Afile specification has the general form:

filename/ext. pass word: d

filename consists of aletter followed by up to seven optional letters

or numbers.

/extls an optional name-extension; 'ext' is asequence of up to three

letters or numbers, starting with aletter.

.password is an optional password; 'password' is asequence of up to

eight letters or numbers, starting with aletter.

;rfis an optional disk-drive specification; -

d' is one of the digits

0,1,2,3.

Note: There can be no blank spaces inside afile specification, trsdos

terminates the file specification at the first blank space.

For example: FILEA/TXT. MANAGER:3 references the file named filea/txt

with the password manager, on Drive 3.

TRSDQg

The name, extension, and drive-specification all contribute to the uniqueness of

afile specification. The password does not. It simply controls access to the file.

File Names

Afile name consists of aname and an optional name extension. For the name,

you can choose any letter, followed by up to seven additional numbers or letters.

To use aname extension, start with adiagonal slash /and add no more than

three numbers or letters; however, the first character must be aletter.

For example:

MODEL3/TXT INVENTORY DATA11/BAS

NAMES/A 12 AUGUST/A 15 WAREHOUS

TEST TEST1 TEST 1/A

are all valid and distinct file names.

Although name extensions are optional, they are useful for identifying what type

of data is in the file. For example, you might want to use the following set of

extensions:

/BAS for basic program

/TXT for ascji text

/CMD for machine-language command file

/DAT for data

One advantage of using extensions is that you can tell by just looking at the

directory what kind of information afile contains.

Another advantage is that trsdos can recognize certain extensions. For

example, if afile has the extension /cmd, the trsdos will load and attempt to

execute that file when you type: filename (ENTER) omitting the extension /cmd.

Drive Specification

If you give trsdos acommand such as: KILL TEST/ Atrsdos will search for

the file test/a first in Drive 0, then in Drive 1,2, and finally in Drive 3until it

finds the file.

Anytime you omit adrive-specification, trsdos will follow this sequence,

unless you use the master command.

It is possible to tell trsdos exactly which drive you want to use by specifying

the drive. Adrive specification consists of acolon followed by one of the digits

0, 1,2, or 3, corresponding to one of the four drives you might be using.

For example: KILL TEST/A: 3tells trsdos delete the file test/a on Drive 3

only.

I»J

!J•~~« TRiS-SQ MODEL

^^^^^|WiSill^^

Anytime trsdos has to open afile (e.g., to list it for you), it will follow the

same sequence. When trsdos has to write afile, it will skip over any write-

protected diskettes.

Password

You can protect afile from unauthorized access and use by assigning passwords

to the file. That way, aperson cannot gain access to afile without using the

appropriate password.

It's important to realize that every file has apassword, even if you didn't specify

it when the file was created. In such instances, the password becomes eight

blank spaces. In this case, the file becomes unprotected —anyone can gain total

access simply by referring to the filename.

trsdos allows you to assign two passwords to afile:

9An "Update word," which grants total access to the information

°An "Access word," which grants limited access to the information (see

attrib)

When you create a file, the Update and Access words are both set equal to the

password you specify. You can change them later with the attrib command.

Apassword consists of aperiod followed by one to eight letters or numbers. If

you do not assign apassword to afile, trsdos uses adefault password of eight

blanks.

For example, suppose you have afile named secret/bas. and the file has

myname as an update and access word. Then the command: KILL SECRETS/

BAS will not cause the file to be killed. You must include the password myname

in the file specification.

Suppose afile is named domain/bas and has blanks for the password. Then the

command: KILL DOMAIN/BAS, GUESS will not be obeyed, since guess is not

the password.

AFew Important Definitions

System vs. Data Diskettes

Asystem diskette is one which contains the trsdos disk operating system

software. Subject to space limitations, it may also contain your own files. A

system diskette must always be in Drive while the Computer is in use.

Adata diskette, on the other hand, does not contain the operating system

software, and therefore cannot be used in Drive 0. It may be used in Drive 1,2

or 3. Such adiskette has amaximum of space available for storing your own

programs and data.

TKSDO!

System, Program, and Data Files

System files include the trsdos operating system software, the basic language

interpreter, the format, backup and convert utilities, and other software

which is released by Radio Shack. These files appear in the Directory with an

"S" attribute. (See dir)

Program files are stored in aspecial format which allows them to be loaded and

executed directly from the trsdos ready level. For example, the basic

interpreter is aprogram file.

Data files include all files that are not in the correct format to allow loading and

executing from trsdos ready. For example, aprogram written in basic will be

stored as adata file. It can be loaded and executed from basic, but not from

trsdos ready.

Master Passwords

Each diskette is initially assigned amaster password during format or backup.

(Your master password for trsdos is password.) The master password allows

you to use backup, purge, and prot on adiskette. Using a diskette's master

password, you may change it (see prot).

1L-JSi ISS22

TRSDOS library Commands

APPEND

Append iles

append source-file destination-file

source-file is the specification for the file which Is to be

copied onto the end of the other file.

destination-file is the specif tcatfQR far the file whic iis to

receive the appendage (addition),

Note: Both source- and destination-files mast Min sscn

format (data files or Basse programs saved with the a

option).

append copies the contents of the source-file onto the end of the destination-file.

The source-file is unaffected, while the destination-file is extended to include the

source-file.

Note: The logical record lengths must match. See dir for more information on

logical record lengths.

Examples

APPEND WORDFILE/C WORDFILE/D

Acopy of wordfile/c is appended to wordfile/d.

APPEND REGI0N1/DAT TOTAL/DAT, GUESS

Acopy of region 1/dat is appended to total/dat, which is protected with the

password guess.

Sample Uses

Suppose you have two data files, payroll/a and payroll/b.

^^^^^^B^^^^B^^^^WMB^^i^M^^^^tt^^^^^^^^^M -fSDOSi

fillfllilfe

WmBf

MBsBBm

PAYROLL/A

Atkins*W.R,,

Baker *J.B. ..

Chambers *C.P.

DodsonfM*W. ,

Ki cKamon >T,Y.

PAYROLL/E

Lewis* G.E

Miller* L..

Peterson* B

Rodriguez *F

You can combine the two files with the command:

APPEND PAYROLL/B PAYROLL/A

payroll/a will now look like this:

PAYROLL/A

Atkins *W.R,

Baker* J.B. ... .

Chaiiibe rs >C.P. ,

Dodson>li W....

Ki ck anion »T.Y..

Lewis* G.E..,,

Miller* L,,

Peterson* B. ...

Rodriguez* F. . .

payroll/b will be unaffected. To see the APPENDed file, type LIST Pf

(ASCII).

Note: Do not load aprogram under basic after an append.

JOLL/A

Change aFie9sPassword

attrib ills (visibilityMC =m?£,upu= :ns.pwi =level)

•ff/e is the file specification.

visibility must be ior n. Tells trsdos whether the file is Invisible (i) or

Non-invisible (n) (see dir). If omitted, visibility is unchanged.

Acc=Mmete!is trsdos \k& access word. If minified the access word

is utisiranyed. If acc =,is used, the access word is set to

blanks. *--

upd =name tells trsdos the update word. If omitted, the update word

is unchanged. If upd =,is used, tits update word is set to

blanks.

ifiC '':'

*mmm

prot =fei/e/ tells trsdos the protection level for access. If omitted,

/eve/ is unchanged.

Level Degree of acces sgranted by access word

full Full access, no protection.

kill Kill, rename, read, execute, and write (gives

total access, i.e., the least-protected).

name Rename, read, execute, and write.

write Read, execute, and write.

read Read and execute.

exec Execute only.

Note: Each level allows access to itself plus all lower levels.

attrib lets you change the passwords to an existing file or makes the file

invisible or non-invisible. Passwords are initially assigned when the file is

created. At that time, the update and access words are set to the same value

(either the password you specified or ablank password).

ATTRIB DATAFILE (

»ACC =JULY14 »UPD=M0USE *PR0T=READ

)

Makes the file invisible, sets the access password to julyw and the update

password to mouse. Use of the access word will allow only reading and

executing the file.

ATTRIB PAYROLL/BAS .SECRET (N»ACC=»)

Sets the access word to blanks. The file is made non-invisible and the protection

level assigned to the update word is left unchanged.

ATTRIB OLD/DAT, APPLES <UPD=»)

Sets the update word to blanks.

ATTRIB PAYROLL/BAS, PW <PR0T=EXEC)

Leaves the access and update words unchanged, but changes the level of access.

Sample Uses

Suppose you have adata file, payroll, and you want an employee to use the

file in preparing paychecks. You want the employee to be able to read the file

but not to change it. Then use acommand like:

•I2

TRSD<

ATTRIB PAYROLL (I »ACC =PAYDAY ,UPD=AV0CAD0 *PR0T=READ

)

Now tell the clerk to use the password payday (which allows read only;; while

only you know the password, avocado, which grants total access to the file.

Protecting BASIC Programs

You may give abasic program execute-only protection using the attrib

command. For example, suppose the program is named test (no password).

Under trsdos ready, execute this command:

ATTRIB TEST (ACC= »UPD=VALLEY ,PR0T=EXEC )

Now test has ablank access password, an update password of valley, and an

access level of execute only. Without using the update password, there is now

only one way to execute the program:

1. Start basic.

2. Type: RUN "TEST"

(This is the only way to access the program. If the operator attempts to load

it instead, basic will erase the program from memory before returning with

READY.)

After the run "test" command, basic will load and execute the program. If

the operator presses (BREAK) or if the program ends normally, basic will erase the

program before returning with the ready message. This makes it impossible to

obtain alisting of the program —unless the update password is used.

Of course, if you use the update password, you may gain full access to the

program.

auto eemmatwl-liae

command-line gives frsdos acommand or the name of an mautable

program file created fay build.

if command'Hne is giwem, the command will fce executed on reset/

power-up.

if commnKi-v<,8i& omitted the previous mjto command is unz^l

Iran the diskette.

"villi

_I'g ITR| 8MO DEL 111 DISK SYSTB

This command lets you provide acommand to be executed whenever trsdos is

started (power-up or reset). You can use it to get adesired program running

without any operator action required, except for typing in the date and time.

When you enter an auto command, trsdos writes command-line into its start-

up procedure, trsdos does not check for valid commands; if the command line

contains an error, it will be detected the next time the System is started up.

AUTO DIR (SYS)

Tells trsdos to execute the command dir (sys) after the start-up procedure.

Each time the System is reset or powered up, it will automatically execute that

command after you enter the date and time.

AUTO BASIC

Tells trsdos to load and execute basic each time the System is started up.

AUTO FORMS (WIDTH=80)

Tells trsdos to reset the printer width parameter each time the System is started

up.

AUTO PAYROLL/CMD

Tells trsdos to load and execute payroll/cmd (must be amachine-language

program) after each System start-up.

AUTO DO STARTER

Tells trsdos to take automatic key-ins from the file named starter after each

System start-up. See build and do.

To Erase an AUTO Command

Type: AUTO (INTER)

This tells trsdos to erase any automatic command. The command will be

deleted the next time you power-up or reset the System.

The acknowledgement: AUTO ="" is displayed after an erasure.

To Override an AUTO Command

You can bypass any automatic command by holding down (ENTER) while pressing

reset. You must continue holding down (ENTER) until you are prompted for the

date during the initialization process.

Ifflmm-

TnQII AQiM:>:;,i:s|«M«

BUILD

Create an Automatic Commai

file is a-file specification which cannot include an extension.

This command lets you create an automatic command input file which can be

executed via the do command. The file must contain data that would normally

be typed in from the keyboard to the trsdos ready mode.

build files are intended for passing command lines to trsdos just as if they'd

been typed in at the trsdos ready level. Note: clear cannot be used in ado

file.

When you enter the build command, build creates the file and immediately

prompts you to begin inserting lines. Each time you complete aline, press

(JEN TIB). (While typing in aline, you can use the usual cursor control keys for

erasures and corrections.)

To end the build file, simply press (BREAK) at the beginning of aline.

First type: BUILD filename

You will then be prompted to type in the command text. You then type in up to

63 characters, then press (ENTER) .You may enter as many lines as necessary.

Press (BREAK) to quit and return to trsdos ready.

ASample BUILD-Fiie

Here's ahypothetical BUiLD-file that initializes the serial interface and the printer

driver:

BETCOM <BAUD=1200,WAIT)

FORMS (WIDTH=B0)

PAUSE SERIAL INTERFACE &'INTER INITIALIZED

ifljjljjl

"LVjK 4*

Clear User Memory

CLEAR (STAR! =33a>3,ESW -•&#M»,MEM =fffffffi)

start =aaa3 tells TRSDOS where to start clearing user memory, aaaa

is afour-digit hexadecimal number from 6Qoo to the end of user

memory. If this option is omitted. 6000 is used. If this option is

end =bbbb teils trsoos to clear user memory to aspecified end. bbbb

is afour-digit hexadecimal number no less than the start

numbei and rse assist than iho 101,1 ol memory. If this option is

used, start =aaaa must also be used.

mem =«« se»& sfi-e memory protect address ccce is a'>ur-digit

hexadecimal number from nuuu to vrr?. If this option is omitted,

the memory protect address is reset to end of user ram.

iill options are omitted all afaiiable ram ir ;leai bo\ me r.j;*'-

protect is reset to end of memory, the Display is cleared, all io

drivers are reset (see Memory Requirements of rRSoos).

This command gets you off to afresh start.

Depending on the options you select, this command will:

9Zero user memory (load binary zero into each memory address above 6000)

•Clear the Display

•Un-protect all memory

See Memory Requirements of trsdos for more information on the memory-

protect address. Note: clear cannot be used in ado file.

Example

CLEAR (START=9000tEND=0A000)

Note: Hexadecimal numbers which begin with aletter must be prefaced by zero

(see above example).

CLEAR (MEM=7000)

Iup-

TRSDC

CLOCK

Turn Oo Clock Display

clock {switch)

svi/iich gives trsdos one of two options, on or off.

If option is omitted, trsdos uses on.

This command controls the real-time clock display in the upper right corner of

the Video Display. When it is on, the 24-hour time will be displayed and

updated once each second, regardless of what program is executing.

Clock display is off at trsdos start-up.

Note: Except during cassette and disk i/o, the real-time clock is always running,

regardless of whether the clock display is on.

Examples

CLOCK

Turns on the clock display.

CLOCK (OFF)

Turns the clock display off.

See time and date.

CLS

Clear the Screen

CLS

This command clears the Display and puts it in the 64 character/line mode.

Example

CLS

;Ejr^'.in --^M WBH3) "RS-80 MODEL 111 DISK SYST!

Illjljjjjii:,

v:«B«t»

Copy aFile or Files

Three forms:

A) copy source-file destination-file

source-file is afile specification for the file to be copied.

destination-file is afile specification for the name and drive of the

duplicate file.

B) copy source-file :d '

source-file is defined above.

:d tells trsdos to copy the file onto drive d, using the same file name.

C) copy Iexf.d

eat is a'wild-card'* file specificz-tiOR in which the fife name is

omitted and the extension is given, trsdos will copy all files

which have amatching extension, regardless of the file name.

.--J Is defined above.

This command copies source-file into the new file defined by destination-file.

This allows you to copy afile from one disk to another, using asingle drive if

necessary. (In the latter case, you must include drive specifications in both file

specifications.) For single-drive systems (Drive 0), both diskettes must contain

trsdos. (i.e., Data diskettes aren't allowed in Drive 0.)

Examples

COPY OLDFILE/BAS NEWFILE/BAS

Copies oldfile/bas into anew file named newfile/bas. trsdos will search

through all drives for oldfile/bas, and will copy it onto the first disk which is

not write-protected.

COPY NAMEFILE/TXT si

This command specifies afile named namefile/txt to another disk.

COPY FILE/EXTS0 si

This command copies file/ext from Drive to Drive 1

________^^ TRSDOS

COPY /BAS:0 :1

tells trsdos to copy all Drive files which have the extension /bas. The files

will be copied onto Drive 1,using their present file names and extensions.

Sample Use

Whenever afile is updated, use copy to make abackup file on another disk. You

can also use copy to restructure afile for faster access. Be sure the destination

disk is already less segmented than the source disk; otherwise the new file could

be more segmented than the old one. (See free for information on file

segmentation.)

To rename afile on the same disk, use rename, not copy.

create fibnsme {lrl =saa.Rtc =&

filename is She file specification.

lhl =ma is the logical record length, aaa is adecimal number

between zero and 255. if omitted. 256 is assumed.

rec =6M is the number of records to allow 'or. bbh is the sBirmv n

records des red l* omitted, no resriMJi are allocated

This command lets you create a file and pre-allocate (set aside) space for its

future contents. This is different from the default (normal) trsdos procedure in

which space is allocated to afile dynamically, i.e., as necessary when data is

written into the file.

If you open the file for sequential writes, trsdos will de-allocate (recover) any

unused granules when the file is closed. If you open the file for random access,

trsdos will not de-allocate space when the file is closed.

;,-;^*/! TRS-80 MODEL III DISK

r~™——;

---; —-

You may want to use create to prepare afile which will contain aknown

amount of data. This will usually speed up file write operations. File reading

will also be faster, since pre-allocated files are less segmented or dispersed on

the disk —requiring less motion of the read/write mechanism to locate the

records

Examples

CREATE DATAFILE/BAS (REC=300> LRL=0)

Creates afile named datafile/bas, and allocates space for 300 256-byte

records

CREATE NAMES/TXT. IRIS (LRL =G4 »REC =50

)

Creates afile named names/txt protected by the password iris. The file will be

large enough to contain 50 records, each 64 bytes long.

CREATE PAYROLL/BAS

Creates afile named payroll/bas but allocates no space to it.

Sample Use

Suppose you are going to store personnel information on no more than 250

employees, and each data record will look like this:

Name (Up to 25 letters)

Social Security Number (11characters)

Job Description (Up to 92 characters)

Then your records would need to be 25 +1 1 +92= 128 bytes long.

You could create an appropriate file with this command:

CREATE PERSONNL/TXT (REC=250 >LRL= 12B

)

Once created, this pre-allocated file would allow faster writing than would a

dynamically allocated file, since trsdos would not have to stop writing

periodically to allocate more space (unless you exceed the pre-allocated

amount).

DATE

Reset or Get Today's Date

bate mm/dd/yy

mm dd yy is the specification for the month {mm), day {dd) and

year {yy).

a»a»

TRSDOS

Each must be atwo-digit decimal number between the following

ranges:

mm 01-12

dd 00-31

yy 00-99

The specifications are an option; however, if one specification is

used, they all must be used.

If mrn/dd/yy is omitted, trsdos displays the current date.

II mm/dd yy &glvei ,iksdos resets the Dale

This command lets you reset the date or display the date.

You initially set the date when trsdos is started up. After that, trsdos updates

the date automatically, using its built-in calendar. You can enter any two-digit

year after 1900.

When you request the date, trsdos displays it in the format: 07/Z5/80 for July

25, 1980.

Examples

DATE

Displays the current date.

DATE 07/18/80

Resets the date to July 18, 1980.

DEBUG

Start Debug Monitor

DEBUG

This command starts the debug monitor, which allows you to enter, test, and

debug machine-language programs.

tip

sIs m

.. JIS TRS-80 MODEL III DISK SYSTB

ISSS»

Its features include:

•Full- or half-screen displays of memory contents

'Commands for modifications to ram and register contents

•Single-step execution of programs

aBreakpoint interruption of program execution

•Transfer of control (Jump)

•"Editing" of disk-files

debug uses the memory area from X'4E00' to X'54FF* (see trsdos Memory

Map), debug can only be used on programs in the user area X'550cr to top.

Examples

DEBUG

Turns debug on. Press ®to quit debugging and return to trsdos.

Turns debug off.

Command Description

Debug commands are usually entered by pressing asingle key. In most cases,

you do not have to press (ENTER) after the command has been typed in. Either

aprompt will immediately be displayed or debug will execute the operation

without further instruction.

In some cases, you will have to enter aspecific hexadecimal value or address

(see rand Jcommands, for instance). Instead of pressing (ENTER) after the

address is typed in, you will have to press CS PACEBAR).

Once you have entered the debug program, you may use any of the following

special commands:

D(Display Memory Contents)

Press ©to display the contents of memory, trsdos will respond with the

prompt: DADDRESS =You should type in the hexadecimal address of the

memory location you wish to see.

The display will be either half- or full-screen, depending on the format you are

currently using (see below).

X(Half-Screen Display)

Press ®to put the Display in the half-screen format. A128-byte block of

memory will be displayed starting with the next lowest address which is afactor

of 16.

Figure 9shows atypical half-screen format.

S(Full-Screen Display)

Press ©to display the contents of a256-byte block of memory starting with the

next lowest address which is afactor of 256.

Note: The last 16 bytes on the Display will be overlaid by any command line

typed in after the full-screen display is updated.

M(Modify RAM)

Press (HD to change to the disk utility display format (see the fcommand).

trsdos will respond with the prompt: MADDRESS =You should type in the

four-digit hexadecimal address of the memory location you wish to modify,

followed by ablank space (anything other than aspace will abort the

command).

The display will change to the memory edit format. The cursor will appear as a

blinking character at the specified location.

To exit the modify mode, press (ENTER) to keep all changes made.

R(Change Register Contents)

Type:

nas, 6M>ft (spacebar:

aa is 1Mb name of one of the register pairs af, bc, de, hc, or pc.

bbbb is the four-digit hexadecimal value which will be loaded into aa.

Ufewer than four digits are typed In before pressing (spacebar) .

leading zeros are sssumect.

I(Instruction Single-Step)

Pressing CD will allow the Computer to execute asingle z-80 instruction. The

display will then be updated.

TRSDOS I

tamsaMMMHraannt osssst--. :- ,;

»Ml«gi«i«lTOpf

'si- •. -i TR -80 MODEL ill DISK SYSTI

Start address

of one 16-byte

"row" of RAM

RAM display-

hex contents

of each byte

ASCII display

(• indicates a

nondisplayable

character)

Z-80 register contents

Op-code Instructions at the "PC" address

Figure 9. Half-Screen Format.

The instruction in the memory contents referenced by the program counter is

executed. The program counter is increased by the appropriate value, and the

control is returned to debug.

debug will not, however, step through acall or jump into a rom address.

C(Call Single-Step)

If you wish to complete an entire call/return sequence, press ©. The call is

then executed and control is returned to debug when the subroutine returns.

Otherwise, this instruction acts just like the Icommand.

You will not be able to step through acall or jump into arom address.

U(Update)

Pressing (U) causes the Display to be updated repeatedly. Press any key to exit

from this mode.

IfiiPii^sififflfilfii

;(Increment Display Address)

If the Display is half-screen, the first location shown is incremented by 16 when

you press CD- If the full-screen format is displayed, the starting address will be

incremented by 256.

—(Decrement Display Address)

If the Display is half-screen, the first location is decremented by 16 when you

press Q. If the full-screen format is displayed, the starting address will be

decremented by 256.

J(Jump)

Press GD to transfer control to amachine-language program, setting optional

breakpoints.

Debug will respond with the prompt: JADDRESS? =

You may type in ajump address and abreakpoint address. The command is

terminated when you press (ENTER) .Type in the addresses in one of three

formats:

TRSDOS mm

jaddress? =aaaa, bbbb Center)

jaddress? =aaaa CI11I1)

jaddbess? =.bhbb mtm

aaaa is afour-digit hexadecimal address specifying the jump

destination- if omitted, the address in the pc register is used.

bbbb is afour-digit hexadecimal address specifying abreakpoint.

Before the Computer executes an instruction at this address, it

will retura control to debug. If this address homitted, control

will no! return to debug.

Notes: Breakpoints must be set at the beginning of z-80 instructions. You may

not set breakpoints in ROM addresses. The breakpointed address will contain an

XT7' until the breakpoint is encountered. Then the original contents will be

restored and debug will take control again.

Q(Quit)

Pressing (D turns off debug and returns control to trsdos.

—

(p1.-T- .> _^^ ^_^ ^E^^_^ ^^^ ^^ ^^ SHE |P% |g*% Hrf" gj^& \/' ^& "jjF If™ jl g

F(File Patch Utility)

This command lets you load and modify the contents of adiskette file.

When you press 2D, debug will respond with the prompt: FILESPEC?. Enter the

name of the file to be patched.

debug will set up afull-screen display showing the first 256 bytes in the file.

You can "page" through the file using the CD and ED keys.

Figure 10 gives atypical display.

In this file-display mode, both hexadecimal and ascii are given for each byte. If

acode has no displayable character, aperiod is shown in the ascii area.

The display control commands are like those for the normal file-display mode:

CD Next page

CD Previous page

To change the file contents, press (M). This puts you in amodify-memory mode

like the one previously described. Use the arrow keys to position the cursor (a

blinking character), then type in the correct contents as ahexadecimal value.

When you are through changing apage on the display, press (ENTER) .The

diskette file will be updated and you will be returned to the file-display mode.

To cancel changes made, do not press [ENTER) ,press [B REAK) .This will put you

back in the file-display mode without updating the diskette file. You may press

CD then CD to restore the page display to its actual contents.

To quit patching afile, press (BREAK) while in the file display mode, debug will

prompt you for anew file specification. Press (BREAK) again and you will be

returned to trsdos ready.

TRSDC

WMBEM61MHBXNNS8&1

Drive #Record #

Byte Offset

within Record

Hexadecimal Contents of

Each Byte ,ASCII Translation

f/m

mmm

HBP

Sip*

Figure 10. Full-Screen Format

-80 MODEL Bii DISK SYSTEI

List the Diskette Directory

DIR :d(lNV,SYS,PRT)

:dl$ the desired drive directory. If omitted, Drive is assumed.

inv lists the invisible user files, if omitted, non-invisible user files are

listed.

sys lists system and user files, if omitted, only non-invisible user files are

listed.

prt lists the directory to the Printer. 1" omitted, in* directory will be listed

on the Video Display only.

If no option is given, trsdos lists non invisible user files in Drive 0.

This command gives you information about adisk and the files it contains.

To pause the listing, press (W). To continue, press (ENTER) .To terminate the

listing, press (BREAK) .

Examples

DIR

Displays the directory of non-invisible user files in Drive 0.

DIR :1 (PRT)

Lists the directory of the user files in Drive 1to the Printer.

Sample Directory Listing

(See Figure 11.)

Definition of column headings

©File Name —The name and extension assigned to afile when it was created.

The password (if any) is not shown.

©Attributes —Afour-character field.

The first character is either i(Invisible) or n(Non-invisible).

The second character is s(System) or *(User) file.

The third character gives the password protection status:

WSBBBBDtiBBBfflB&&®HBffl

ligiJiiiifc

TRSDOS

s^^^^w^ ililiii|lllipll|i

WBB Jllllllli «WS iff

^MillllifS?|f

illlUBt

Illl

® ©

///./ / /

Figure 11. Directory Listing.

xThe file is unprotected (no password).

aThe file has an access word but no update word,

uThe file has an update word but no access word.

BThe file has both update and access words.

The fourth character specifies the level of access assigned to the access word:

Total access

1Kill file and everything listed below.

2Rename file and everything listed below.

3This designation is not used.

4Write and everything listed below.

5Read and everything listed below.

6Execute only.

7No access.

®Number of Free Granules —How many free granules remain on the diskette.

©Logical Record Length —Assigned when the file was created.

©Number of Records —How many logical records have been written.

©Number of Granules —How many granules have been used in that

particular file.

MmmemMMWMfflBBmm

]

.. .Jfe TRS-80 MODEL 111 DISK SYSTE

©Number of Extents —How many segments (contiguous blocks of up to 32

granules) of disk space are allocated to the file.

©End of File (eof) —Shows the last byte number of the file.

®Creation Date —When the file was created.

Begin Aeto Command Input from aBUILD-FIle

do command-line

command-line is the name of file created with build. No extension should

be specified. ii";£ file will automatically be given tine extension Bin,

This command reads and executes the lines stored in aspecial-format file

created with the build command. The System executes the commands just as if

they had been typed in from the Keyboard.

Command lines in abuild file may include library commands or file

specifications for user programs.

When do reaches the end of the automatic command input file, it returns control

to TRSDOS.

The debug and clear command cannot be included in abuild file.

In addition to executing trsdos library commands, you can load and execute

user programs from aDO-file. You will probably want to make your program

name be the last line in the DO-file.

Examples

DO STARTER

trsdos will begin automatic command input from starter, after the operator

answers the Date and Time prompts.

AUTO DO STARTER

Whenever you start trsdos, it will begin automatic command input

from starter.

TRSDOSiL

Sample Uses

Suppose you want to set up the following trsdos functions automatically

on start-up:

FORMS (WIDTH =80)

CLOCK (ON)

Then use build to create such afile. If you called it begin, then use the

command: AUTO DO BEGIN to perform the commands each time TRSDOS

starts up.

Duplicate Output to Video and Printer

dual {switch)

switch is one of two options, on or off. II omitted, trsdos uses on.

This command duplicates all video output to the Printer, and vice versa. It takes

effect immediately.

Notes:

Video and printer output may be different because of intrinsic differences

between output devices and output software.

2. Using the dual command will slow down the video output process.

3. The dual command cannot be used during route and vice versa.

4. The printer should be ready when you execute the command.

Sample Use

For aprinted copy of all system/operator dialog, type: DUAL (EMTER)

To turn off the dual process, type: DUAL (OFF )(ENTER)

f-l- \$Z~ TRS-80 RflODEL lii DISK SYSTEM

DUMP

Store aProgram Into aDisk File

dump file (start =aaaa, end =bbbbjm =ccccrelo =tfcteW)

fffe is the file specification

start =sasa is the start address cf memory black, aaaa must be afour-

digit hexadecimal number greater than or equal to x'7000.'

end =bbbb is the end address of the memory block, bbbb must be afour-

digit hexadecimal number.

tra =cccc is the transfer address where execution starts when the program

is loaded, cccc must be afour-digit hexadecimal number. If this

option is omitted, the command will default to trsdos re-entry.

relo =dddd is the start address for relocating or loading the program back

into memory. cfcWtf must be afour-digit hexadecimal number. If this

option is omitted, no relocation will take place.

Mote: Addresses must be hexadecimal form, without the x' 'notation.

You must add the prefix "0" to any hex number which begins with a

letter.

This command copies amachine-language program from memory into a

program file. You can then load and execute the program at any time by entering

the file name in the trsdos ready mode.

Examples

DUMP LISTER (START =7000 >END=7100 ,TRA=7004

)

Creates aprogram file named lister/cmd containing the program in memory

locations x-7000" to x'7ioo\ When loaded, lister/cmd will occupy the same

addresses, and trsdos will protect memory beginning at x'70oo\ The program is

executable for the trsdos ready mode.

DUMP PR0G2 (START=7000»END=7F00»TRA=8010(RELO=8000>

Creates aprogram file named prog2/cmd containing the program in addresses

x-7000- to x'7foo'. When loaded, prog2/cmd will reside from x'sooo' to x'SFucr.

Execution will start at x'soio*.

rii

TRSDOS '

sue _ .

ERROR

Display Error Message

error number

number is adecimal number for atrsdos error code.

This command displays adescriptive error message. For example, after

receiving the message, * * ERROR 47 * * you may respond with the

command: ERROR 47 (ENTER)and trsdos will display the full error message.

For acomplete list of error codes and messages, see the Technical Information

section of this manual.

FORMS

Set Printer Parameters

FORMS (WIDTH =W, LINES =I)

width =wis the maximum number of characters per output line. If aline

reaches this length, trsdos will insert acarriage return to force anew

Sine. If this option is omitted, the current maximum width will be

used. To disable the maximum line width feature, use width =255.

trsdos will not force new lines.

lines =/is the number of Sines per page, trsdos does not use this value.

However, basic will use it in computing the necessary page

displacement for execution or if lprint ckrs(12j is executed. If lines =/

is omitted, the current value is used.

This command lets you modify the printer forms control features of trsdos.

The default values are:

Maximum line width: 132

Lines/page: 60

forms also sets the line count to 0.

.JtJ.3 TF1S-80 MODEL 111 DISK SYSTEM

Examples

If you are using 8'/2"-wide forms, you will probably want to set width =80:

FORMS (WIDTH=80)

If you are using 14"-long forms, you may want to set lines =78.

FORMS (LINES=7B)

This change will allow the basic statement, lprintchr$02), to advance apage

by the correct number of lines.

Notes:

1. The width you specify is stored in ram location 16427. The lines you

specify is stored in ram location 16424.

2. The Printer must be ready when you execute this command.

FREE

Display Disk Allocation Map

mum

FREE :tf(PRT)

:tf is the drive specification. 1! omitted, Drive is used.

(prt) tells trsoos to send the map to the Printer.

it emitted, trsdos sends the map to the Video Display only.

This command gives you amap of granule allocation on adiskette. (A granule,

1280 bytes, is the unit of space allocation.) It also shows the location of the

directory and any flawed sectors.

When adiskette has been used extensively (file updates, files killed, extended,

etc.), files often become segmented (dispersed or fragmented). This slows the

access time, since the disk read/write mechanism must move back and forth

across the diskette to read and write to afile.

free helps you determine just how segmented your disk files are. If you decide

you'd like to re-organize aparticular file to allow faster access, you can then

copy it onto arelatively "clean" diskette.

TRSDI

dBttmSKR

Examples

FREE

Displays afree space map of the diskette in Drive 0.

FREE (PRT)

Lists the free space for Drive to the Printer.

FREE si (PRT)

Lists the Drive 1map to the Printer.

ATypical FREE Display

Four special symbols are used in the free map.

Unused Granule

Direct Directory Information

XAllocated Granule

Flawed Granule Contains aFlawed Sector (Unusable)

Atypical free map display is shown in Figure 12.

Disk Name

All six granules in

track 2are allocated

,^.^v£.,^ Wk

Figure 12. Free Map.

mmm*

1The directory is located

on track 17.

HFT P

Explanation of TRSDOS Command

help command

command is the specific trsdos command or subject on which wou need

help. If omitted or if an invalid subject is given, trsdos will list all

available subjects.

Ii;v^ t

\wP!fflPi$if ;qn] YSTEM

WBBMSB/SBBBS&MBHttMBSBMM

If you type in the following: HEELP BACKUP (ENTER) trsdos will respond with

the syntax format, adefinition of the command, and an explanation of

the abbreviation.

HELP SYNTAX tells trsdos to explain the help descriptions.

KILL

Delete aFile or Group of Files

Two syntaxes:

A) kill file

file is afile specification

B) kill iextd

/ex/ is afile extension that must contain three characters.

:d is adrive specification. It musihs provided.

This command deletes one file or agroup of files, depending on which form is

used. Form Adeletes the specified file. If no drive specification is given,

trsdos deletes the file from the first diskette that contains it.

Form Bdeletes all files with aspecified extension, regardless of the file name of

each file. If no drive specification is given, the files will be deleted from the first

drive that contains amatching file specification.

Examples

KILL TESTPROG/BAS

Deletes the named file from the first drive that contains it.

KILL JOBF

LE/ IDY, PASSWORD :1

Deletes the named file from Drive 1.The file has apassword of password.

KILL /BAS:0

Deletes from Drive all files having the extension /bas.

LIB

Display Library Commands

LIB

This command lists to the Display all the library commands. For help with a

command, use help.

Example

LIB

LIST

List Contents of aFile

LIST fi7e(PRT,SL0W,ASCII)

file is the file specification.

prt tells trsdos to list to the Printer. If omitted, only the Video Display is

used.

slow tells trsdos to pause briefly after each record. If omitted, the listing is

continuous.

ascii tells trsdos to list the file in ascii format. If omitted, hexadecimal

format is used.

This routine lists the contents of afile. The listing shows both the hexadecimal

contents and the ascii characters corresponding to each value. For values

outside the range (X'20\ X'7F'), aperiod is displayed.

Use the ascii option for text files and basic programs saved with the aoption.

Note: Only ascii codes xw-x'7F' are sent to the Printer. Bit 7is always

set to 0.

During the listing, press (@D to pause, (ENTER) to continue, or (BREAK) to exit.

Examples

LIST DATA/TXT (ASCII )

Lists the contents of data/txt in ascii format.

LIST FILE/A (SLOW)

Lists the contents of file/a, pausing after each record.

LIST PROGRAM/CMD (PRT)

Lists the file program/cmd to the Printer.

LOAD

Load aProgram File

load file

file is afile specification for afile created by trie dump command.

This command loads amachine-language program file into memory. After the

file is loaded, trsdos returns to the trsdos ready mode.

You cannot use this command to load abasic program or any file created by

basic. See the basic Reference Manual for instructions on loading basic

programs.

Note: The file must load into the user area (X'7000'-top).

Examples

LOAD PAYROLL /PT

Sample Use

Often several program modules must be loaded into memory for use by amaster

program. For example, suppose payroll/pti and payroll/pt2 are modules, and

menu is the master program. Then you could use the commands:

LOAD PAYROLL/PTI

LOAD PAYROLL/ PT2

to get modules into memory, and then type: MENU to load and execute menu.

MASTER

Set Master Mead/1 'WkDrive

MASTER (DRIVE =a)

ais the drive specification. If omitted Drive is set as the master drive.

This command allows you to assign aspecified drive as the Master Read or

Write drive in the system. When searching for afile, trsdos will start with the

master drive.

If the file is not found on the specified drive, trsdos will continue searching on

the next higher-numbered drive.

Example

After you enter the command: MASTER (DRIUE =1)Drive 1becomes the

master drive.

PATCH

Change the Contents off aDisk Fie

patch file (add =aaaa,nm =bh,zm =cc)

file is the file specification

add =aaa& specifies the address at which the data is found, aaaa is afour-

digit hexadecimal number.

find =bb specifies the string you wish io find (or compare to), bb is a

hexadecimal sequence.

chg =cc specifies the new coirtsnls foi the. byte(s). ce is ahexadecimal

sequence.

Note: This utility is for machine language programs only.

1.B&2 "a TRQ-ft( nummi

This command lets you make minor corrections in any disk file, provided that:

You know the existing contents and location of the data you want to change.

2. You want to replace one string of code or data with another string of the

same length.

You can use patch to make minor changes to your own machine-language

programs; you won't have to change the source code, re-assemble it, and re-

create the file.

Another application for patch is to allow you to implement any modifications to

trsdos that may be supplied by Radio Shack. That way, you do not have to

wait for alater release of the operating system.

Sample Use

Suppose you want to change seven bytes in amachine-language program file.

First determine where the seven-byte sequence resides in ram when the program

is loaded. Then make sure your replacement string is the same length as that

of the original string. For example, you might write down the information

as follows:

File to be changed: vread

Start address: X'5280'

Sequence of code to be changed: xcd2D25E5 -

Replacement code: X'00000009'

Then you could use the following command:

PATCH VREAD (ADD=5280 »FIND=0CD2D25E5 >CHG=00000009

)

pause message

message is the message to be displayed during the pause execution. This

is optional. If omitted, pause will he displayed by itself.

JRSDOSJ^jg|:

*'<amssF^

This command is intended for use inside ado file so trsdos can print amessage

or reminder.

To continue after the pause, trsdos prompts you with the message:

PRESS (ENTER)- TO CONTINUE

Example

PAUSE INSERT DISKETTE «Z1

trsdos displays pause, next the message and then prompts you to press (ENTER)

to continue execution.

PAUSE

PRESS <ENTER)- TO CONTINUE

trsdos displays pause and then next prompts you to press (ENTER) to continue.

See build and do for sample uses.

Use or Change aDiskette's Master Password

PR0T:«f(PW,L0CK)

:d is an optional drive specification. If omitted, Drive is used.

pw tells trsdos you want ie change the master password.

lock tells trsdos to assign the master password to all unprotected user

files, If omitted, the unprotected files remain unprotected.

prot lets you use the master password to protect all unprotected files at once, or

to change the master password.

The master password will be needed to backup the diskette, so be sure to

remember it!

Note: The master password on the trsdos factory-release diskette is password.

Untune

^raJ3Q*W*

PROT :0 (PW)

Tells trsdos to change the master password on the Drive diskette, trsdos will

prompt you first for the old master password, then for the new master password.

PROT si (LOCK)

Tells trsdos to assign the master password to all unprotected user files, trsdos

will first prompt you for the master password.

PURGE

Delete Files

purge :d (file-type)

:d is the drive which contains the disk to be purged.

file-type must be one of the following:

sys AH System and User files (no Invisible)

inv All Invisible and User files (Mo System)

all AH files on disk (User, System, Invisible)

If lie-type is onlfteif, trsdos defaults to Use rfiles.

This command allows quick deletion of files from aparticular diskette. To use

purge, you must know the diskette's master password, (trsdos System

diskettes are supplied with the password password.)

When the command is entered, trsdos will ask for the diskette's password.

Type in up to eight characters. Press (ENTER)if you typed fewer than eight

characters. The System will then display user filenames one at atime,

prompting you to kill or leave each file.

PURGE :1

trsdos will purge user files from Drive 1.This would include basic programs.

PURGE :1 (I NO)

trsdos will purge all invisible files in Drive 1.

TRSDOS

Note: System diskettes contain some files which are not shown in any of the

directory listings. You may delete these files with aspecial form of purge:

purge* :d (file-type)

The asterisk tells trsdos to ask you if you want to delete the System files. If

you do delete them, the diskette becomes adata diskette and may only be used

in Drive 1, 2or 3.

The other parts of this command are as explained previously. However, be sure

to do the purge using Drive 1,2or 3, since the diskette will become "non-

system" during the purge.

Change Where Program Loads Into Memory

fslo file (add =aaaa)

:. //Zeis the file specification..- './ ***'....*.. -

add =aaaa specifies the new laac! addre ss aaaa is sfour-digit hexadecimal

number referring to maddress in the oser memory aaaa must be in

''"/";

:the user area, of ram.

This command allows you to change the address at which the program loads into

memory. It does not change the program itself.

Note: This command may be useful in conjunction with dump.

Example

RELO PROGRAM/CMD (ADD=6578)

trsdos will load the program program/cmd at the new memory address

of 6578.

me osamme newname

oldname is the old file name.

newnatm is the new file name.

The file name may iwW» adrive specification and apa ;sword.

The new file nanus should not include adrive specification or password.

This command lets you rename afile or program. Only the name/extension

is changed; the data in the file and its physical location on the diskette

are unaffected.

rename cannot be used to change afile's password protection. Use attrib

to do that.

rename also checks to see that the intended new name does not duplicate a

filename currently on the same diskette. If it does, the command is cancelled

and an error message is displayed.

Examples

RENAME MATHPAK MATHPAK/BAS

Tells trsdos to add the extension to the filename.

RENAME ABCDE/DAT ABCDEF/DAT

Tells trsdos to change the filename only.

RENAME PAYR0LL1/TXT.GSR PAYR0LL2/TXT

Tells trsdos to change the filename; the password is retained automatically.

RENAME FILE1:3 FILE2

Tells trsdos to change the filename of the file on Drive 3.

._/^^sn

Routing I/O Devices

ROUTE (SOURCE =33, DESTIN =bb)

source -aa specifies the source mfisvice.

destim =bb specifies the destination i/o dewice.

aa and 66 may be any meaningful combination of the following two-letter

abbreviations: ^^

do (Display)

pia {Printers

kb (ifefboart)

Ri (RS-232 input)

ro '(RS-232 Output)

If the source and destination wjs5?3i! as ;omitted, trsdos resets i/o Bribers

tc theii original i/o routes. The source anil destination devices mast loth lie

output or both be input.

This command allows you to route i/o devices automatically. For example,

trsdos can route information from the Printer (PR) to the Display (DO).

Note: route cannot be used in conjunction with the dual command.

Examples

ROUTE (SOURCE=PR*DESTIN=D0)

trsdos will route your Printer output to the Display.

ROUTE

i/o drivers are returned to their original state.

For further details on routing i/o see "Routing Input/Output" in the

Model III Manual.

iKO-OU

SETCOM (OFF.WORD =8, BAUD =A, STOP =C.PARITY =ABWlfe)

off tarns rs-232-c off, --

word =ais the number of bit/byte desired, amust be either 5, 6, 7, or 8.

depending on your needs. If omitted She word length is not changed.

baud =bspecifies the baud rate, bmust be adecimal number between 50

and 9600. if omitted, the baud rate is not changed.

stop =cspecifies the numbei of stop bits emisl be either Im2. If

omitted, stop bits are not change'd.. -

parity =ddetermines whether the parity is odd, even, or none, dmust be 3

(none), 1(odd), or 2(even). If omitted, parity is not changed.

.mot/e type either wait or nowait

Options must be entered in the order stawst.

IJ ail the 2p!isri are omitted, tosdos displays the Current rs-232-g settings.

This command initializes rs-232-c communications via the serial channel. Before

executing it, you should connect the communications device to the Model III.

See the Model III Operation Manual for adescription of rs-232-c signals used.

See Using the RS-232-C Interface in the Model III Manual for further details.

Examples

SETCOH (WORD =7»BAUD =300»STOP=1 ,PARITY=3 tWAIT)

This would set the rs-232-c to seven bit words, 300 baud, one stop bit, no parity,

and place it in the wait mode.

SETCOM

The command without specifications will display the current settings.

The following program will allow you to use your Computer as aterminal. For

further information, refer to the Operation section of your Model III Operation

Manual.

Note: This program executes at 300 Baud.

TRSDGS|Si

^mmmmsm^

5DEFINT A-Z

10 POKE 1G830,

15 POKE 1G888. (5*lB)+5

20 DEFUSRO =&H005A: REH

40 X=USR0(0)

60 DEFUSRI =&H0050

B5 DEFUSR2 =&H0055

70 CI =1S872

80 CO =1G8B0

90 'CHECK FOR SERIAL IN

110 X=USRK0)

120 C* =CHR*(PEEK(CI) )

130 PRINT C*

140 'CHECK FOR KEYBOARD

150 C* =INKEY$

1G0 IF C$ ="" THEN 110

1G5 PRINT C*s

170 POKE CO, ASC(C$)

180 X=USR2(0)

200 GOTO 110

'INTEGER VARIABLE FOR SPEED

'DON'T WAIT FOR SERIAL I/O

'TX/RCU AT BAUD RATE 300

SET UP CALL TO $RSINIT

'CHARACTER INPUT BUFFER

'CHARACTER OUTPUT BUFFER

PUT

'CALL *RSRCU

'LOOK AT INPUT BUFFER

'IF C=0, NOTHING HAPPENS

INPUT

'NO KEY, SO GO CHECK SERIAL

'SELF ECHO

'PUT CHARACTER INTO OUTPUT BUFFER

'QALL $RSTX

'GO CHECK SERIAL INPUT

Tape/Disk Transfer

tape (s =source, d=destination)

som'smiil destination are abbreviations for tS estorage devices to

•lis© usstf; ^

'":' "t-Tape ./

dDisk '

. : RRandom access memory

Mote: tape can only be used with machine-language programs, basic

programs must be CLOAoetf and csavescI.

This command transfers z-80 machine-language programs from one storage

device to another. The following transfers are possible:

•Tape to disk

HillBBt

Sifts!!!!1

\lHiIlls' ."':.

8Disk to tape

•Tape tO RAM

Examples

TAPE (S =T»0 =D

31 DISK SYSTI

Starts atape-to-disk transfer, trsdos will prompt you CASS?. Select the desired

baud rate (H for high, Lfor low), trsdos will then prompt you to press (ENTER)

when the recorder is ready to play to the Computer. When you press (ENTER) ,the

tape will begin loading.

Note: If no asterisks flash, the recorder volume may need adjustment or the

baud rate setting may be incorrect.

trsdos will read the file name from the tape and use that name for the disk file.

It will copy the program to the first write-enabled diskette, starting with the

master drive (see master) .

TAPE (S=D»D=T)

Starts adisk-to-tape transfer, trsdos will prompt you for the desired cassette

baud rate, then for the diskette file specification. Then it will tell you to press

(ENTER) when the cassette recorder is ready to record from the Computer.

TAPE <S=T>D=R)

Starts atape-to-RAM transfer, trsdos will prompt you for the cassette baud rate,

and will tell you to press (EMTER) when the recorder is ready to play to the

Computer. After loading the program, trsdos will begin execution at the

transfer address specified on the tape.

time hh:mm:ss

hh:mm:ss specifies the hour hh, mwutj mm, mi second ss.

Each must be atwo-digit decimal number between tie following ranges:

hh 0-23

mm 0-59

ss i-59

If hh:mm:ss is giwen, trsdos resets the time.

If hh:mm:ss is not giwen, trsdos displays fte current time.

TRSDOS

warn

This command lets you reset or display the time.

Time uses a24-hour clock. For example, 1:00 P.M. is displayed as 13:00.

You initially set the time when trsdos is started up. After that, trsdos updates

the time automatically, using its built-in clock.

When you request the time, trsdos displays it in this format: 14:15:31 for

2:15:31 P.M.

Examples

TIME

Displays the current time.

TIME 13:20:00

Resets the time to 1:20:00 P.M.

Note: If the clock is allowed to run past 23:59:59, it will re-cycle to zero, the

date will be incremented, and the clock will continue to run.

Write-Protect Via Software

wp (drive =d)

dspecifies the disk drive to be protected. If omitted, all drives will be

unprotested.

Diskettes can be protected from being overwritten by this command. It is a

software write-protect rather than a hardware write-protect (such as the write-

protect tab on the diskette).

Only one drive may be protected at a time.

To unprotect adrive, making it accessible to writing, simply enter the command

wp without options or with adifferent drive number specified. The wp command

will not override awrite-protect tab.

ODEL 111 DISK SYSTEM

Examples

WP (DRIME=1)

trsdos will write-protect the disk in Drive 1

trsdos will eliminate write-protection on all drives.

TRSDQ

BACKUP

Create an Exact Copy of an Original Disk

backup -.source -.destination

source specifies the drive containing the original diskette. If omitted.

trsdos will prompt you for this information.

-.destination specifies the drive containing the diskette to receive the copy, if

.omitted, trsdos will prompt for It.

•.source en& destination may reference line same drive.

backup copies the contents of the source disk to the destination disk. This gives

you a"safe" copy of the disk. Always keep an extra copy of data or programs

you have stored on your disks.

Note: Both source and destination diskettes must be write-enabled.

trsdos will prompt you at each step after you type: BACKUP

If you omitted the source/destination-drive numbers, trsdos will begin with the

prompts: SOURCE DRIVE NUMBER.

Type in the number of the drive that contains the source diskette and press

OTTER) .

DESTINATION DRIVE NUMBER?

Type in the number of the drive that will contain the destination diskette and

press (ENTER) .

SOURCE DISK MASTER PASSWORD?

Type in the password assigned to your source diskette.

DISK CONTAINS DATA* USE DISK OR NOT?

Type in Y(Yes) or N(No).

DO YOU WISH TO RE-FORMAT THE DISK?

Type in Y(Yes) or N(No).

\,jSE trs-80_model ail

If you specified the source/destination drives, trsdos will request the

password, skipping the first two steps.

trsdos will then take charge of formatting and verifying the destination disk as

well as letting you know if there are any errors or flawed tracks.

CON VERT

Model Ito Model III File Conversion Utility

CONVERT

Model Iformatted diskettes cannot be used in the Model III Disk System.

However, the convert utility can read aModel Idiskette and copy its non-

system files onto aModel III trsdos diskette. This diskette may then be used

normally in the Model III Disk System. The original Model Idiskette may still

be used in aModel IDisk System, since it is unchanged by convert.

convert does not convert or change data; it converts the file storage format.

For this reason, Model IDisk basic programs may require slight changes before

they will run properly in the Model III Disk System. Model Imachine-language

programs may require major or minor changes before they will run in the Model

III Disk System. You may make these changes on the Model Idiskette before

using convert, or on the Model III diskette containing the converted files.

For hints on program conversion, see:

•Technical Information in this manual

8Technical Information in the Model III Manual

•The manual, Instructions for Converting Specified Model IPrograms for use

on trs-80 Model 111.

Drive Usage

In two-drive systems, the files must be copied onto aModel III system diskette

in Drive 0; in three- or four-drive systems, the files may be copied onto adata

diskette in Drive 1,2or 3

During the conversion process, the Model Idiskette is referred to as the

"source"; the Model III diskette, the "destination." The source diskette cannot

be in the same drive as that of the destination diskette.

Password Protection

convert is designed to preserve the password security of each file that it

transfers. To accomplish this and still allow the copying of protected files,

convert follows different procedures depending on the access and update

passwords on each file.

In the simplest case, afile has blank access and update passwords. The copied

file will be given blank passwords. (If you have aModel IDisk System with

trsdos 2.3, you may use the prot command to remove all passwords from all

files. This will simplify the convert process. Do this on the Model Isystem

before you attempt to convert to Model III.)

In another case, the access and passwords are different. If the access password

is blank and the update is not, then trsdos will prompt you for the update

password. If you know the update password, type it in. The file will be copied

with access and update passwords set to the old update password. If you don't

know the update password, simply press (ENTER) .The file will be copied with the

access password set to blanks and the update password set to an unknown value.

If the access and update passwords are not blank and they are not the same,

trsdos will not copy the file, but will print the message, FILE SKIPPED, and

continue with the next file in the source directory.

Sample Use

Get the Model Idiskette ready. If you have aModel IDisk System with trsdos

2.3, try to remove all passwords from all your files. This will prevent any

problems with passwords. The password protection may be restored with the

Model III attrib or prot commands after the conversion is complete.

Using the Model III Disk System, you must always have aModel III trsdos

diskette in Drive 0. trsdos ready should be displayed. Type: CONCERT CENTER) .

The program will ask, SOURCE DRIVE?. Type in the number of the drive

containing the Model Idiskette, and press (ENTER) .Then the program will ask,

DEST INAT ION DR IVE? .Type in the drive number and press CENTER) .In two-

drive systems, you must use Drive as the destination.

During the conversion process, the name of each file will be displayed as it is

copied. If password information is needed, trsdos will prompt you for it. If

you know the update password, type it in and press (ENTER) .The file will be

copied and given the same update password. If you do not know the update

password, simply press (ENTER) ,in which case the file will be copied and given

an unknown update password.

If afile name on the source diskette is already used on the destination diskette,

trsdos will print this message: FILE EXISTS, USE IT?. If you type Y,

trsdos will copy the file. The previous contents of the Model III file will be

lost. If you type N, trsdos will skip the file, and get the next one from the

Model Idiskette.

FORMAT

FORMAT :rf

f/ Si-icjifies fe? disk d^vc which contains the diskette to te f!rro&*?ei. If d

f? omitted, tbsdos will prompt you for Ms wwrjWierL

This command lets you prepare data diskettes (either new or disks which contain

undesired data or programs), leaving a maximum amount of space for your

program and data files.

Note: Data diskettes may only be used in Drives 1,2, and 3except during a

BACKUP Or FORMAT.

format takes ablank (new or magnetically erased) diskette, records track/sector

boundaries on it, then initializes it with and creates adirectory.

When format detects a non-blank diskette, it will display awarning message:

DISK CONTAINS DATA* USE DISK OR NOT?

Type Y(Yes) and press (ENTER) if you do want to reformat, N(No) and press

(ENTER)if you want to save the disk information.

format will lock out any defective tracks to prevent data from being lost in

these areas.

If you begin to get read errors during access, reformat the disk.

Example

FORMAT si

After you are prompted for DISKETTE NAME? and MASTER PASSWORD)

TRSDOS will format Drive 1

TRSDOf: :-

Set Up for 50 Hz AC power (non-USA users)

DO HERZ50

starts the utility to change the system for 50 Hz operation, herzso is a do-

file.

This utility is provided for customers in areas where the ac power is 50 rather

than 60 Hz. It should not be used by any other customers, herzso simply places

apatch on the diskette that changes the clock speed for 50 Hz users.

herzso is aDO-file that makes achange in the software of trsdos. Only the

Drive diskette is changed. Be sure it is write-enabled before you start the do-

file. Once the herzso change is done, it will remain in effect for that diskette.

To perform the change, type:

DO HER250

Once the change has been made, you will need to reset the system to put the

change into effect. This loads the new software into ram.

lpc

The lpc utility program allows trsdos to ignore multiple carriage return

commands. Without lpc, atop-of-form (LPRiNTCHR$(i2» command will add an

extra carriage return/line feed each time it is executed. Also, lpc masks the high

bit of each data byte, allowing you to send certain intercepted codes to the

printer. For instance, the basic statement lprint chr$( 140) will send code 140-

128= 12 (lprintchr$(12» to the Printer.

;•- 'in

f^g TRS-80 MODEL 111 DISK SYSTEI

The printers that require lpc are:

Line Printer III (26-1156)

Line Printer VI (26-1166)

Daisy Wheel WP50 (26-1157)

Qume Daisy Wheel (26-1 157A)

Daisy Wheel II (26-1158)

and all future printers.

Printers that do not require lpc:

26-1150, 1152, 1153, 1154, 1159, and the aversion of lpiii (26-1 156A).

You must load the lpc program before you load an application program. The

easiest way to do this is to copy lpc onto your data/program diskette and then

use the auto command to load lpc automatically each time you use the system.

For instance, type:

COPY LPC: i:0 (ENTER)

Then, to make lpc an auto command on the diskette, type:

AUTO LPC/CMD (ENTER)

Whenever you use your program diskette, lpc will automatically load into

memory and you can use the program as usual.

lpc locates into the highest available memory. There is no need to set MEMORY

SIZE to protect lpc. It "hides" itself. However, you still need to set memory if

required by your application program, lpc will be killed if the clear command

is used.

Warning: Once the lpc utility program is loaded and installed, you should not

reload it except after areset. Reloading re-installs the program and uses up more

space each time! lpc will not execute if the Printer has been routed elsewhere.

Also, if lpc has been executed and then the Printer is routed elsewhere, the

original printer driver will regain control after the routing.

MEMTEST

Test Memory

MEMTEST

This program tests your Model Ill's memory (read only and random access). In

trsdos ready, just type MEMTEST and press (ENTER) .

ISDO

The program automatically tests all memory locations, no matter what memory

size you have. First it checks read only memory (rom); if everything is okay, it

automatically goes on and checks random access memory (ram). If all ram

checks out okay, the program continues.

If the program detects a rom or ram error, it will display adetailed message.

Repeat the test to make sure it is avalid error condition. Write the message

down and contact your nearest Radio Shack for assistance.

Note: memtest changes the entire contents of ram. Before running it, be sure

you have saved any valuable code you may have in ram.

XFERSYS

Transfer System Files

XFERSYS

xfersys lets you upgrade your version of Model III trsdos by copying all

system files from anew release diskette (source) onto apreviously released

diskette (destination) (i.e., version 1.2to version 1.3,etc .)

System files which already exist on the destination diskette are replaced by those

from the source diskette. Files which do not exist on the destination diskette are

added. User files (program and data) are unaffected.

Steps to upgrade adiskette

Make backup copies of all diskettes to be upgraded. This is an important

precautionary step. These backup copies should be kept until the upgrading

process is complete and confirmed.

Note: Both source and destination diskettes must be write-enabled.

Insert the new release of trsdos into Drive and press the reset button. Then

type XFERSYS CENTEH) .

After the program heading appears, trsdos will prompt you with DISKETTE TO

CONVE RT READY IN DRIVE 1(Y/)?. Type Y(yes) or (quit) and press

(ENTER) .

The upgrading process will then take place. When the process is complete,

trsdos will tell you so and take you back to trsdos ready.

Note: If an error occurs, including your trying to upgrade anon-system diskette,

the operation will be cancelled and take you back to trsdos ready.

-:-'•"" T^S-80 MODEL 1!I DIS KSYST1

Contents of This Section:

Disk Organization

File Structure

System Routines for Assembly i/o

Data/Device Control Blocks

Physical and Logical Records

Fundamental trsdos i/o Calls

Additional Routines and Storage Addresses

trsdos Error Codes/Messages

Disk Organization

Each trsdos system diskette contains a trsdos system, autility command

library, and afile directory.

Each diskette is single-sided and has 40 tracks of information. Each track

contains 18 sectors of 256 bytes each.

Normally, data read/write operations may be initiated only at sector boundaries,

and must consist of exactly 256 bytes. However, trsdos allows the user to have

maximum flexibility with minimal effort by automatically blocking and de-

blocking all file accesses to user-specified logical record lengths, even if this

requires "spanning" of two sectors.

The system disk file structure allows maximum use of disk file space by

automatically segmenting files across adiskette in several small pieces. These

pieces are correlated into one logically contiguous file by the system without

your needing to know the physical file location. This structure eliminates time- Av,

consuming disk-packing operations. ^v4?

File Structure *i Jr

Atrsdos file is composed of one or more segments of storage space. Each £, ^

segment consists of from one to 32 physically contiguous granules of storage. A^Ji

granule is the minimum allocatable unit of storage, and consists of three sectors ^f ^p

(768 bytes). ^

Since afile is always lengthened by granules, asmall amount of free storage is v

generally present at the end of every file. This free storage allows minor file

additions to be made in space which is physically contiguous to the file.

Every time adisk file is extended (either initialized or lengthened), extra

granules may be allocated to that file, depending on the file's accumulated

length, diskette space, saturation, etc. These extra granules, along with all

TRSDOS KSfeS^Mt

granules after the one containing the file's eof mark, are recovered and returned

to the system when the file is closed.

ATRSDOS ile

FILE:

LRN1 LRN2 LRN3 LRNN EOF

EXTENT 1EXTENT 2

SEGMENT: GRANULE 1GRANULE 2GRANULE 32

GRANULE: SECTOR XSECTOR X+

SECTOR X+2|

BYTE1 BYTE 2BYTES BYTE 256

SECTOR:

LRN: Logical Record Number, used to specify an individual, user-defined

logical record. Such alogical record is the smallest unit of

information which can be addressed during disk input/output (a

physical record is the unit which is actually read from or written to

disk).

File: Agroup of logical records; the largest unit of information which can

be addressed by atrsdos command.

Sector: Aphysical record, composed of 256 contiguous bytes.

Granule: The minimum allocatable unit of storage for any file.

Extent: One contiguous allocation of granules.

System Routines for Assembly-Language I/O

This information is provided for customers who wish to write their own

assembly level i/o routines. An explanation of the calling sequence and

parameters for each necessary i/o routine is given. Aknowledge of z-80 machine

code is assumed.

The following notations are standard in this section:

(HL) =xxxx Registers hl contain the address of (point to) xxxx in machine

format. (If address of xxxx =34B2H then the values in the

registers are: h=34; l=B2). Other register pairs will also be

indicated this way.

a=xx Register acontains the numeric value of xx in binary form.

Acomplete list of error codes and their meanings appears at

the end of this chapter. Other registers will also be indicated

this way.

-'•< Bay

-.;.

"1---' 'SM

mFRS-80 MODEL IBS DISK SYSTEM

Z=OK Zero flag is set (OK) if successful return from the system

routines.

Xnnnn

or nnnnn

Hard ram address in hex notation (e.g., 402D is X'402D').

lrl

BUFFER

Logical Record Length, 1-255 bytes only. You can define

records any length you wish up to 255 bytes maximum. A

length of zero is aspecial case for physical records only, and

indicates the lrl =256 bytes.

256 user-designated bytes in ram for trsdos to read sectors

from or write sectors into. If lrl =o, this area is the

responsibility of the user to manage before and after i/o. trsdos

manages this area if lrl is between 1and 255 bytes. Do not

alter this area when using logical record processing.

UREC (User Record) The address of the contiguous ram byte-string

assigned by the user as his logical record area. Its length must

be equal to lrl. It is adifferent area from buffer.

lsb/msb Least-significant byte followed by most significant byte. This is

the standard z-80 format for addresses.

$name The "$" is prefixed to all system locations and call routines, so

they will not be confused with trsdos commands or utilities.

For example, sopen.

DCB before $OPEN and after $CLOSE

The dcb (device control block) is defined as 50 contiguous bytes of ram

designated by the user. Before $open and after $close, it is aleft-justified,

compressed (no spaces) ascii string, as in astandard trsdos filespec. The string

is terminated with acarriage return.

816 24

name/eXtP

asswr

Notes: /ext, .password, and :d are optional.

$stands for acarriage return (X'OD')

::rSm>(''Sim''eiiX.

''mm

DCB while $OPEN

Address Length Explanation

DCB +O 3 Reserved

+3 2 Physical Buffer address (lsb/msb)

+5Offset to delimiter at end of current record

+6File drive number residence

+7Reserved

+8eof offset of last delimiter in last physical record

+9lrl (logical record length)

+10 2nrn (next record #

—

$open sets =xwoo' —lsb/msb)

+12 2ern (ending record #—(last in file) lsb/msb)

+14 50 Reserved

NRN Next Record Number defines which record is to be read or written by the

next system call for $read or $write. It is automatically incremented by one

after each system call. In order to process random files, use the $posn call to

direct trsdos to the record you wish to transfer next.

ERN Ending Record Number is the last record number currently in the file. It

is put into the directory at SCLOSE time, so if it is expected to be correct, the user

must close his files after adding records to afile. This value may also be used to

position to end of file so that new records may be added to the end of the file. To

position to the end of file use acall to sposn with arecord number of ern +i.

$posn is described later.

Physical and Logical Records in TRSDOS

Aphysical record is defined as one sector of disk. One sector of disk contains

256 user data bytes. The artificial term "granule" is defined to be 3sectors of

disk space. There are 6granules on each of the 40 tracks on the disk. Agranule

is the least amount of space allocated by trsdos. For programming purposes,

the physical records in afile are numbered from to N. The largest record

number (N) in afile will then be 3times the number of granules allocated minus

one ((3*G) -1). All trsdos granule allocations are made as needed at the time

of write, not when the file is created.

Bytes Sectors Granules Tracks Disk

256

768

4608

184320

31—

18 61

720 240 40

Disk Space Table: For each 5l

A" Disk Drive

Alogical record is defined by the user of tRsdos. It may be anywhere from 1to

255 bytes in length. Once afile is opened with aspecific lrl (Logical Record

Length), the length is fixed until the file is closed. To change afile's lrl, you

must close it and re-OPEN it with the new lrl.

Each opening of the file sets asingle, fixed record-length, trsdos will "block"

logical records into (or from) one physical record for maximum space utilization

on the disk.

Blocking is putting more than one logical record into one physical record. For

instance, four 64-byte logical records will fit into one 256-byte physical record.

Alogical record may be broken into two parts by trsdos in order to fill the last

portion of one physical record entirely before beginning to use the next physical

record (i.e. records are spanned). This occurs when the physical record length is

not an even multiple of the logical record length.

If the user wishes to do his own blocking, he may specify alogical record length

of bytes at the time of init/open and must himself manage the contents of the

physical record buffer area of 256 bytes, trsdos will not move alogical record

for the user if lrl =0; in this particular case it will only read/write the physical

record to/from the buffer. Once control is shifted to your program, you will have

about 20 bytes of stack size left.

Fundamental TRSDOS I/O Calls

There are 17 fundamental trsdos routines involved in handling file i/o. These

are:

$BACKSPACE $POSN

$CLOSE $PUTEXT

$DIVIDE $RAMDIR

$DMULT $READ

$FILPTR $REWIND

$INIT $SYNTAX

SKILL $VERF

$OPEN $WRITE

$POSEOF

The detailed calling sequences and discussions for each of these routines follow.

Note that all of these system calls use register fand do not restore its value

before return. In order to apply this data properly, you should read through all of

these descriptions and clear up all of the points that are not obvious to you by

using other reference materials. If you are successful in doing this you will find

that trsdos is aworkable tool for your programming ideas.

$INIT —17440/X'4420'

$init is provided as an entry point to trsdos which will create anew file entry

in the directory and open the dcb for this file. $init scans the directory for the

filespec name given in the dcb. If the filespec name is found, $init simply opens

TRSD

the file for use. If the name is not found, anew file is created with the filespec

name.

Entry Conditions

(HL) =buffer (see beginning of this section for notation)

(DE) =DCB

B=LRL

CALL $INIT

Exit Conditions

iy =changed

z=OK

ccarry flag is on if anew file was created

a=trsdos error code. (Error codes listed at end of this chapter)

$OPEN—17444/X?4424?

$open provides away to open the dcb of afile which already exists in the

directory. The dcb must contain the filespec of the file to be opened before entry

to $OPEN.

Entry Conditions

(HL) =BUFFER

(DE) =DCB

B=LRL

CALL $OPEN

Exit Conditions

Z=OK

z=if file does not exist.

a=trsdos error code.

iy =changed

$POSN— 17474/X?4442'

$posn positions afile to read or write arandomly selected logical record. Since

it deals with logical records, the proper computation is done to locate which

physical record(s) contain the data. Following a$posn with a$read or $write

will transfer the record to/from ram.

[ISK

Note that positioning to logical record zero sets the file to read the first logical

record in the file. To position to end of file in order to add new records onto the

end, use the record number ern +1

Entry Conditions

(DE) =dcb (must have been opened previously)

bc =Logical record number to position for.

CALL SPOSN

Exit Conditions

Z=OK

a=trsdos error code

$READ— 17462/X'4436?

If lrlo, $read transfers the logical record whose number is in the dcb as nrn

into the ram area addressed as urec for the length lrl as defined at open time.

The record comes from "buffer" defined at open time. If trsdos must read a

new physical record to satisfy the request, it will do so. "Spanned" logical

records will be re-assembled as necessary. $read automatically increments nrn

by 1in the dcb after the transfer is completed. $init/open set nrn^x'oooo' in

order to read the first record with the first read.

If lrl =o, $read transfers one physical record into buffer, defined at open

time, from the disk file. Registers hl are ignored. $read increments nrn as

above.

(HL) =urec if lrl is not zero. Unused if lrl =o.

(DE) =dcb

CALL SREAD

Exit Conditions

Z=OK

a=trsdos error code. (eof =x*ic or x'id*)

(see errors 28,29 for eof or nrf)

$WRITE^ 17465/X?4439'

If lrlo, swrite transfers the one logical record from the ram area addressed

as urec for the length lrl as defined at open time. The record goes into the

buffer which was defined at open time. If trsdos must write aphysical record

in order to satisfy the request, it will do so. "Spanning" will be handled by

trsdos as necessary. At $init $open time the dcb value of nrn is set to X'oooo'

so that the first record will be written. After each logical record is transferred,

the nrn value in the dcb will be incremented by 1

If lrl =o, $write transfers one physical record from buffer into the disk file

using the nrn in the dcb. buffer is defined at $init/open time only. The dcb

value nrn is updated as above, after the write.

Entry Conditions

(HL) =urec if lrl is not zero. Unused if lrl =o

de =dcb

call $wr1te

Exit Conditions

Z=OK

a=trsdos error code.

-17468/X'443C

The only difference between $verf and swrite is that $verf writes one physical

record to disk and then reads it back into aspecial trsdos ram area not defined

by the user. This special area and the original write buffer are then compared

byte by byte to assure that the record was successfully written.

Entry Conditions

(HL) =Same as swrite above.

(DE) =dcb

CALL SVERF

Exit Conditions

Z=OK

a=trsdos error code.

$PUTEXT— 17483/X?444B ?

This routine will add an extension to afilename if an extension does not already

exist. An extension to afilename may be useful for identifying the type of data

in the file.

r~" '"M mam

Entry Conditions

(DE) =DCB

(HL) =The extension to be added to the file

CALL SPUTEXT

Exit Conditions

None

$BKSPC —17477/X'444§ 9

This routine positions the file record pointer to the previous record.

Entry Conditions

(DE) =DCB

CALL $BKSPC

Exit Conditions

z=Valid position

nz =Invalid position in file

$REW1NB—17471/X9443F9

Point to the beginning of the file. This routine positions the file pointer to the

first record in the file. This is useful when the same file must be processed more

than once.

Entry Conditions

(DE) =DCB

Exit Conditions

z=Good file specification

nz =Bad file specification

CALL SREWIND

$POSEOF—17480/X94448'

Point to the end of file. This routine positions the file pointer to the last record in

the file. This may be used to extend asequential access file.

TRSDOS1

WBBf tmmmmmm

Entry Conditions

(DE) =DCB

CALL SPOSEOF

Exit Conditions

z=Good file specification

nz =Bad file specification

$SYNTAX— 17436/X9441C

Move afile specification to dcb. This routine takes afile specification and

checks it for validity and moves it to adcb so that the file may be opened.

Entry Conditions

(HL) =Filename

(DE) =DCB

CALL SSYNTAX

Exit Conditions

z=Good file specification

nz =Bad file specification

$DIVIDE —17489/X'445 1

The divide routine takes a16-bit dividend and an eight-bit divisor. After

division, the quotient replaces the 16-bit dividend and the remainder replaces the

eight-bit divisor.

Entry Conditions

hl =Dividend

A=Divisor

CALL SDIVIDE

Exit Conditions

HL =Quotient

a=Remainder (0 indicates no remainder).

t: feii™*^isJ TRS-80 Ml

$OMULT— 17486/X9444E'

The multiply routine uses a 16-bit multiplicand and an eight-bit multiplier. After

multiplication takes place, the product replaces the 16-bit multiplicand.

Entry Conditions

hl =Multiplicand

A=Multiplier

CALL SDMULT

Exit Conditions

H=High order byte

L=Middle order byte

a=Low order byte

High Middle Low

IIR^17©40/X9429!F

This routine allows you to examine adiskette directory (one entry or the entire

directory) or the diskette's free space. The information is written into auser

specified ram buffer.

Only non-system files will be included in the ram directory.

Entry Conditions

hl =ram Buffer. If c=0, size =1761 [max #*22+ 1]. If c= 1to 96,

size =22. If c=255, size =64.

b=Specified drive number

c=Function switch:

Contents of CResults

Gets entire directory into ram. (See ram Directory Format).

1-96 Gets one specified directory record into ram, if it exists. (See

ram Directory Format)

255 Gets free-space information (See ram Directory Format).

call sramdir

Exit Conditions

nz =Error occurred.

z=No error. (HL) =directory or free-space information.

TRSDC

1«^—Sg

RAM Directory Format

The directory is made up of records, one per file. All values are hexadecimal.

Each record placed in user ram is in the following format:

Byte Number Contents

0-14 filename!ext:d (left-justified followed by spaces)

15 Protection Level, binary 0-6

16 Byte EOF, binary 0-255

17 Logical record length, binary 0-255

18-19 Last sector number in file, binary lsb, msb

20-21 Number of Granules allocated clsb.msb) binary

22 "+"(marks the end of directory list after entire directory.)

Free Space Message Format

***nnnnn Free Granules***

Where nnnnn is adecimal number. The entire message is Ascn-coded.

$FILPTR— 17037/X'428B?

This routine provides information on any user file that is currently open. It

enables you to obtain the drive number and the logical file number for any file

and should be used in conjunction with sramdir.

Entry Condition

(DE) =Data Control Block (dcb) defined when file was opened.

CALL $FILPTR

Exit Conditions

nz =Error occurred.

z=No error. The following registers are set up:

b=Which drive contains the file (0,1,2, or 3).

c=Logical file number (1-96)

Note: This operates with user files only.

$CLOSE— 17448/X94428?

$close closes afile from the last processing done. It is very important to do

a$close on every file opened before the program ends. If you do not close

afile, the directory entry for this file is incorrect if any new records have been

--"-iTRS-80 MODEL il

written into the file. Other cases are not given here, but it is very important to

trsdos that all of the "housekeeping" be complete for file management.

Entry Conditions

(DE) =DCB

CALL SCLOSE

Exit Conditions

Z=OK

a=trsdos error code.

$JKILL —174§2/X9442C

skill deletes the directory entry for a file and releases the disk storage. The file

may be open or closed; skill will operate in either case.

Entry Conditions

(DE) =DCB

CALL SKILL

Exit Conditions

Z=OK

a=trsdos error code.

Additional Routines and Storage Addresses

$JP2D08 —16429/X'402D?

This routine transfers control to trsdos ready.

Entry Conditions

JP SJP2DOS

Exit Conditions

None

TRI: ".

$OATE— 12339/X93(B39

$TIME— 12342/X ?3CI36 9

These routines return the date and time in ascii format:

Date: mm/dd/yy

Time: hh/mm/ss

Entry Conditions

(HL) =Eight-byte buffer to receive the date/time text

CALL SDATE

CALL $TIME

Exit Conditions

(HL) =Date or time text

IATLOC —16922/X9421 A9

$TIMLOC —169 19/X942179

These locations store the date and time in binary format:

SDATLOC (Three bytes): yy dd yy

STIMLOC (Three bytes): ss mm hh

$EMROSP— 17417/X944t)9 ?

This routine displays atrsdos error message determined by the contents of the

accumulator (A). This register contains an error code (0 =no error) after

completion of any system routine.

Entry Conditions

A=trsdos error code (see Table at the end of this section). In atrsdos error

code, bits 6and 7are normally reset (off). So $errdsp interprets them as

controls.

Bit #

CALL SERRDSP

wmmmmsmem

Set

Return to caller upon

completion

Give detailed error message

Not Set (Normal

Condition)

Return to trsdos upon

completion

Give error number only

{Iltl TF on ii

oU IV iSK SYSTEi

Exit Conditions

None

Sample Use

CALL $SYSRTN 5ANY SYSTEM ROUTINE

JR ZfOKGO iCHECK FOR ERROR

!THE FOLLOWING INSTRUCTION SETS BIT 8(DETAILED

!ERROR MESSAGE) AND BIT 7(RETURN TO CALLER AFTER

iDISPLAYING MESSAGE

OR C0H 5BINARY 11000000

CALL $ERRDSP 5NOW CALL ERROR DISPLAY

»CONTINUE HERE UPON RETURN FROM ERROR DISPLAY

JYOUR ERROR HANDLER MAY GO HERE

OKGO 5CONTINUATION AFTER $SYSRTN WITH NO ERROR

$DSFMR— 17433/X94419?

This command displays the directory listing of all non-protected user files in a

specified drive.

Entry Conditions

(X'427r) =Ascn-coded drive number "0," "1," "2," or "3"

CALL SDSPDIR

All registers are changed.

IOS— 17049/X94299?

This routine executes atrsdos command and returns to trsdos ready.

Entry Conditions

(HL) =Text of trsdos command, terminated by X'OD.'

JP SCOMDOS

Exit Conditions

None

TRSDOS c

**t**mmmsemm

$CMOOOS— 17052/X?429C 9

This routine executes atrsdos command and returns to the caller.

Entry Conditions

(HL) =Text of trsdos command, terminated by X'OD;

Exit Conditions

All registers are changed.

Caution: trsdos commands will overlay ram up to X'6FFF.'

$CMDIXT^ 16933/X 94225?

This is the start address of abuffer containing the last command line entered

under trsdos ready. Using this buffer, your program may recover parameters

that were included in the last command line.

For example, given aprogram named editor/cmd, we want the operator to

select an input file name when the program is loaded and executed from trsdos

ready:

trsdos ready

editor myfile

The program, editor, can recover the name of the file in the scmdtxt buffer.

Note: On entry to aprogram, (HL) =First non-blank character following the

program name.

;NB^17425/X9441F

This storage location contains the highest address available. It is normally the

same as the physical end of ram, but you may change it for special purposes.

The address is in lsb, msb sequence.

J^j™iifeiiiMiiliMilli

ipm

L&«'>'' TRS-80 MODEL 111 DBSK SYSTEM

l^^^iB ""~~~———

—

————-~^^^~^^^^>^

TRSDOS Error Codes/Messages

No Error Found

1CRC Error During Disk I/O

2Disk Drive Not In System

3Lost Data During Disk I/O

4CRC Error During Disk I/O

5Disk Sector Not Found

6Disk Drive Hardware Fault

7"Undefined Error Code**

8Disk Drive Not Ready

9Illegal I/O Attempt

10 Required Command Parameter Not Found

11 Illegal Command Parameter

Time Out On Disk Drive

I/O Attempt To Non-System Disk

14 Write Fault On Disk I/O

15 Write Protected Disk

16 Illegal Logical File Number

17 Directory Read Error

18 Directory Write Error

19 Invalid File Name

20 GAT Read Error

21 GAT Write Error

22 HIT Read Error

23 HIT Write Error

24 File Not Found

25 File Access Denied Due to Password Protection

26 Directory Space Full

27 Disk Space Full

28 Attempt to Read Past EOF

29 Attempt to Read Outside of File Limits

30 No More Extents Available

31 Program Not Found

32 Invalid Drive Number

33 "Undefined Error Code"

34 Attempt to Use Non-program File as aProgram

35 Memory Fault During Program Load

36 "Undefined Error Code"

37 File Access Denied Due to Password Protection

38 I/O Attempt to Unopen File

39 Invalid Command Parameter

40 File Already In Directory

41 Attempt to Open File Already Open

•hi! '

IIP

Mtt9 ^^*giiipip«»s»«,,

Introduction

Start-Up

Under trsdos ready, type:

BASIC CENTER)

trsdos will load basic and begin the "initialization dialog."

If you want to recover aDisk basic program after returning to trsdos for adir

or other trsdos command, use this command under trsdos ready:

BASIC *CENTER)

You will go directly to Basic's ready mode without any initialization dialog. If

you had aprogram in memory, it should still be there. You may not be able to

run the program. To be safe, you should immediately save the program, go to

trsdos, then start basic again (no asterisk).

Note: If you have overlaid user memory while in trsdos, your program will be

erased. In such acase, you should not restart basic, but should use the normal

basic start-up procedure.

Initialization

When you start Disk basic, you are first asked, HON MANY FILES?. This lets

you specify the maximum number of files that will be "open" or in use at once.

(See open.) Type in an appropriate number and press CENTER) ,or simply press

CENTER) and basic will provide for three files.

For example, if your program requires one input file and one output file, you

should ask for two files.

Note: Normally, basic will give all your data files arecord length of 256.

(See File Access Techniques.) If you wish to set the record length of each file

individually, use the suffix vfor "Variable" after the number of files.

For example,

HOW MANY FILES? 3M CENTER)

tells basic to give you three lie-buffers, and to let you set the record length of

each file when that file is first opened.

Note: Disk basic automatically creates abuffer for loading, saving, and

merging basic programs. This buffer exists in ram below any data file buffers

you may request. It is always available for program i/o, regardless of how you

answer the files? question.

a«.j

WRB&

B»fl-.!

ODEL ISI DISK SYSTEI

After you answer the files question, basic will ask: MEMORY SIZE? Simply

press (ENTER) without typing anumber. You will then have the maximum amount

of ram available for use by basic.

If you will want to load and use machine-language programs or routines, you

will have to protect your basic memory from these machine-language programs.

In such acase, respond with the highest memory address (in decimal form) you

want basic to use for storing and executing your basic programs. Addresses

above the number you specify will then be protected from use by basic.

Example:

MEMORY SIZE? 32000 dMIER)

causes basic to protect addresses above 32000. If you have 16K of ram, this

means that you'll have 32767-32000 =767 bytes protected for storing your

machine-language routines.

After you answer the MEMORY SIZE? question, Disk basic will display the

following information:

Which version of Disk basic you are using

2. Copyright information

3. The number of free bytes available

4. The number of concurrent files you have requested.

To exit from Disk basic and return to the trsdos ready mode, type:

CMD"S" (ESTER)

This results in anormal return to trsdos, without re-initialization of the system.

You may recover your program if you haven't changed user memory while in

trsdos. Use basic *.

^SKSi..;--;

Enhancements to Mode! WBASIC

Disk basic adds many features which are not disk-related. They are listed below

along with abbreviated descriptions. Detailed descriptions follow in alphabetical

order.

Abbreviations

CMD"A"

CMD"B"

CMD"C"

CMD"D"

CMD"E"

CMD'T'

CMD"J"

CMD"L"

CMD"0"

CMD'T"

CMD"R"

CMD"S"

CMD'T"

CMD"X"

CMD"Z"

DEFFN

DEF USR

INSTR

LINE INPUT

MID$ =

NAME

USRrt

Hexadecimal-constant prefix

Octal-constant prefix

Many commands have abbreviations

Return to trsdos with error message

Enable/Disable (BREAK)

Delete spaces and remarks from aprogram (compression)

Display directory for specified drive

Display previous trsdos error

Return acommand to trsdos

Convert calendar date

Load z-80 subroutine or program file into ram

Alphabetizes (sorts) astring array only

Check printer status

Start real-time clock display

Normal return to trsdos (jump to exit routine)

Turn off real-time clock display

Cross-reference of reserved words, string variables, or

strings in aprogram

Duplicate output to Display and Printer

Define basic- statement function

Define the entry point for an external machine-language

routine

Instring function; find the substring in the target string

Input aline from keyboard

Replace portion of the target string (used on left of equals

sign)

Renumber aprogram in ram

Call external routine (« =0,1,2, ... ,9)

&H and &O (hex and octal constants)

Often it is convenient to use hexadecimal (base 16) or octal (base 8) constants

rather than their decimal counterparts. For example, memory addresses and byte

values are easier to manipulate in hex form. &h and &o let you introduce such

constants into your program.

&h and &o are used as prefixes for the numerals that immediately follow them:

ODEL ill DISK SYSTEI

tMdddd

dddd is a1to 4digit sequence composed of Hexadecimal numerals

0,1,...9,A,B.....F.

&oddddd

ddddd is asequence of octal numerals 0,1, ...J and &oddddd< =177777

decimal.

Note: The ocan be omitted from the prefix &o. Therefore &oddddd=.&ddddd.

The constants always represent signed integers. Therefore any hex number

greater than &H7FFF, or any octal number greater than &.QI1111, will be

interpreted as a negative quantity. The following table illustrates this:

Octal Hex Decimal

&1 &H1 1

&2 &H2 2

&77777 &H7FFF 32767

&100000 &H8000 -32768

&100001 &H8001 -32767

&1 00002 &H8002 -32766

&177776 &HFFFE -2

&177777 &HFFFF -1

Hex and octal constants cannot be typed in as responses to an input prompt

or be contained in adata statement. Often the hex or octal constant must be

enclosed in parentheses to prevent asyntax error from occurring.

Examples

PRINT &H5200* &O51000

prints the decimal equivalent of the two constants (both equal 20992).

POKE &H3C00, 42

puts decimal 42 (ascii code for an asterisk) into video memory address hex

3C00.

HOI/'' DJtDI^I

»»m

"]!

Mode! Ill Disk BASIC Abbreviations

Abbreviation Meaning

®List Previous Program Line

CD List Current Program Line

CD Edit Current Program Line

ucx List Program Line xx

EXX Edit Program Line xx

DXX Delete Program Line xx

AXXX,XXXX Automatic Line Numbering Beginning at Line xxx,

Incrementing by xxxx.

,& A99

Return to TRSDOS

CMD"A':

This command allows you to return to trsdos with an error message:

OPERATION ABORTED

Sample Use

After an input/output error occurs in abasic program, you might want to exit to

trsdos and print amessage.

CMD"A"

the following will be displayed:

OPERATION ABORTED

TRSDOS READY

4t»ttt*4<4*t*4*»tft

,s""RS-80 MODEL ill DISK SYSTEM

CMD "B"

Enable/Disable BREAK Key

cmd"B", 'switch'

switch is either on or off. switch must be enclosed in quotation marks.

This command enables or disables the (BREAK) key. While the function is "off,"

the (BREAK) key will be ignored except during cassette or printer output or during

serial input/output.

The (BREAK) key will remain disabled even after the program has ended. To

enable the (BREAK) key, use the cmd"B","ON" command. Returning to trsdos

via the cmd"S" or cmd'T' commands will also enable the (BREAK) key.

Examples

CMD"B" »"0FF"

Disables the (BREAK)key.

CMD"B" »"0N"

Returns the (BREAK) key to its normal function.

CMD "C"

Compress Program

crvtD '%', options

options may be either r(delete remarks) or s{delete spaces). If both

options are omitted, remarks and spaces are deleted. If only one is

owittec?, only the specified action is lakes.

This command allows you to compress aprogram so that it requires less

ram and less storage space on diskette. You can elect to remove all remark

DISK BASIC |

statements (beginning with rem or ') or to delete all spaces between basic

keywords. Spaces inside quotes will not be deleted.

Example

Your program reads as follows:

850 RESTORE: ON ERROR GOTO 800 'DOG PROGRAM

8B0 READ COMPANY* 'PET STORE

870 PRINT RIGHT$(C0MPANY*»2> >: GOTO 860

880 END

If you want to delete the Remarks (lines 850 and 860), type in the command:

CMD"C" .R

and the program will now read:

850 RESTORE: ON ERROR GOTO 800

860 READ COMPANY*

870 PRINT RIGHT*(C0MPANY*»2) »:G0T0 860

880 END

If you then wanted to delete the spaces, type in:

CMD"C" ,S

and the program would read:

850 RESTORE :ONERRORGOTO800

860 READCOMPANY*

870 PRINTRIGHT*(C0MPANY*»2) »:GOTO8S0

880 END

You could obtain the same results by typing:

CMD"C"

Note: Always provide the closing quotes on string literals in your basic

program. Otherwise cmd"C" may not function properly. For example, in

10 PRINT "THIS IS ATEST"

the second quote should be used even though omitting it will not cause an error.

CMD"D"

Display the Directory of aSpecified Drive

mo"o:d" /";

dis the drive specification

By entering the command cmd"d:<5P',you can obtain aspecified diskette's

directory from basic without returning to trsdos. Only unprotected, visible

files will be displayed. The drive specification is not optional and must be

specified for all drives, including Drive 0.

Example

If you type in the command:

CMD"D:1"

the directory for Drive 1will be displayed.

Display Previous TRSDOS error

CMD"E"

This command displays the last trsdos error message. If no errors have

occurred prior to the command, the message NO ERROR FOUND will be

displayed.

Example

If you have atwo-drive system (0 and 1) and you type:

SAME "PROGRAM: 3"

Disk basic will return aDISK I/O ERROR .To find out what kind of I/O error

occurred, type: CMD "E"(ENTER) and Disk basic will return with DISK DR IVE

NOT IN SYSTEM.

CMD"I"

Execute TRSDOS Commands from Disk BASH

mo"\", command ''

command is astring expression containing atrsdos command or a z-80

program file name. If it is astring constant, it must be enclosed in

quotes.

You may execute trsdos commands directly from basic by using cmd'T'.

This is similar to cmd"S", except that it lets you include acommand or z-80

program for trsdos to execute

As long as basic is not overwritten by the execution of the program or

command, control will return to basic; otherwise, control will return to trsdos.

(trsdos commands all overlay basic; your z-80 program may not if it loads

above basic.)

Example

CMD"I" ("PROGRAM"

returns you to trsdos and executes the program file program.

CMD"!" >M

returns you to trsdos and executes the command contained in a$.

CMD"J"

Calendar Date Conversion

cmd"J", source, destination

source is astring expression containing the date to be converted. Its

contents may be in either of two formats:

as mm/dd/yy

bj -yy/ddd

Format agives the date in month-day-year sequence. Format bgives

the day of the year (from 1to 365 or 366 for leap years), In format b,

the hyphen Is required.

destination is astring variable to contain the converted Me. If source Is in

format a, destination will contain the day of year. If source is in

format b, destination will contain the elate in format a.

This command converts dates back and forth between two formats: the standard

month, day, year, sequence; and ayear, day of year, sequence. The content of

the source string determines which way the conversion goes

itiijfiiaMiiiiiiiiiiiiiiiMaii^i^

iSwil

:LJgTRSjO MODELJBB DISK SYSTEj

Example

CMD"J" >"11/30/80" >D$

Returns the day of the year in d$.

CMD"J" ,"-79/300" ,D$

Returns the month, day, year, equivalent in D$ (the date for the 300th day

of 1979).

Sample Program

10 CLEAR 50

20 LINE IN PUT "ENTER FIRST DATE (MM/DD/YY) "5 FD$

30 LINE INPUT"ENTER SECOND DATE (MM/DD/YY) "?SD$

40 CMD"J" tFD$» Dl$

50 CMD"J" >SD$> D2$

B0 Yl =MAL(RIGHT$(FD* ,2)

)

70 Y2 =UAL(RIGHT$(SD$,2)

)

B0 Jl =VAL(RIGHT$(D1* ,3) )

90 J2 =MAL(RIGHT$(D2$>3) )

00 SI =Y1*365 +Jl

10 S2 =Y2*3G5 +J2

20 PRINT "THE INTERVAL BETWEEN DATES IS"

30 PRINT ABS(S1-S2)i "DAYS "5

40 PRINT "(IGNORING LEAP-YEARS),"

50 INPUT "<ENTER> TO CONTINUE" 5A$

G0 GOTO 20

CMD"I 9

Load Z=8(Q) Routine imto RA

cmd"L", mtiiim

routine is astring expression containing afile specification for az-80

routine or program created by the dump command. If routine is a

string constant, it must be enclosed in quotes.

CMD"L" loads az-80 (machine- language) routine into ram. It would normally

be used to load a z-so subroutine which is to be accessed directly from basic.

100

nOHK

The z-80 routine should load into high-RAM and must not overlay the memory

protect area reserved when you first entered basic (i.e. ,the MEMORY SIZE?

prompt). If you do not overlay basic or trsdos, control will return to basic

after the program is loaded.

Example

The command:

CMD"L" »"PR0G"

will load aprogram file named prog into ram.

CMD"L" ,P$

will load aprogram which has been specified as p$.

CMD"09'

Sort ("Order' 9

)am Array

cm"Q",x,array (start)

xis an integer variable containing the namiier of items to he sorted.

amy (start) specifies an array element. The array contains the data to be

sorted, and start is the suiissript of the first element to he sorted. Tins

array most be one-dimensional, siring type. The string elements in

array may be of any length.

This command sorts (orders) aone-dimensional string array, i.e., alist. You

may sort all or part of the array, depending on the values you give to x and start.

Sample Program

10 CLEAR 10 *25 +50

20 DIM A* (9)

30 FOR WD =TO 9

40 PRINT "ENTER NORD «" 5WD+1

50 INPUT A*(WD>

G0 NEXT WD

70 NZ =10; CMD"0" >HI, A*(0)

80 PRINT "HERE IS THE SORTED LIST

90 FOR WD=0 TO 9

'ROOM FOR 10 WORDS +EXTRA

'LIST OF TEN (0-9)

BttatSiftk

101

iim

u%i4' '~4i$ hP B'-itU xg»' &L# Issai fe^^i b! i!J a^y k^^ to ^fe? sS ^W^ !3 OWs &i

100 PRINT A$(WD!

110 NEXT WD

CMWV

Check Pi 'vier Status

status is astring variable

cmd'T" makes it possible for Disk basic to check the status of the printer.

Unlike the video display, the printer is not always available. It may be

disconnected, offline, out of paper, etc. In such cases, when you try to output

information to the printer, the Computer will wait until the printer becomes

available. It will appear to "hang up." To regain keyboard control (and cancel

the printer operation), press (BREAK) .

Suppose you have aprogram which uses printer output. If aprinter is not

available, you don't want the Computer to stop and wait for it to become

available. Instead, you may want to print amessage such as PRINTER

UNA MAILABLE and go on to some other operation.

To accomplish this, you need to check the printer status. cmd"P" can be used to

check the printer's status at any time. It returns the contents as an Ascii-coded

decimal number. The specific value of this number depends upon the type of

printer you are using as well as its status at any particular time. The value may

then be printed or examined by the program.

Only the four most significant bits are used in this "status byte." In binary,

these must be: "0011" or else the print operation will not be attempted. To

check for this "go" condition, and the status byte with 240 and compare the

result with 48. The meaning of each status bit depends on which printer you

use. See the printer owner's manual for bit designations.

Sample Program

10 CHD"P" ,}{$

20 SJ1 =VAL(X$) AND 240

30 IF STX <> 48 THEN PRINT "PRINTER UNAVAILABLE": STOP

40 PRINT "PRINTER AVAILABLE"

50 REM PROGRAM MAY NOW CONTINUE

102

iH C^ %./f lc5> Pi £?

13l\ ol^kS

WllgsMiSiii

CMD66 E"

TUmirn On Clock-Display

CMD"R"

This command controls the real-time clock display in the upper-right corner of

the Video Display. When it is on, the 24-hour time will be displayed and

updated once each second, regardless of what program is executing.

Note: The real-time clock is always running (except during cassette or disk i/o),

regardless of whether the display is on or off.

Example

To turn on the clock display type: CMD "R"To turn the display off, type: CMD "T

CMD"S"

Return! to TRSEM ..' 5

CIWD"S"

To exit from Disk basic, returning control to trsdos, simply type in the

command:

CMD"S"

To return to basic and recover your program, use BASIC *. However, recovery

will not always be possible. See basic *.

The basic prompt lets you know you are in Disk basic.

READY

103

\..'~Y: TRS-80 MODEL BBS PflSBC SYSTEM

\;-f4 ^™

To exit, type in:

CMD"S"

and the trsdos prompt will appear.

TRSDOS READY

CMD"T"

Ikm Off Clock-Display

CMD"T"

This command turns off the real-time clock display function.

However, the clock continues to run.

Example

To stop the clock display update type: CMD"T"

To start the display, type: CMD"R"

CMD "X"

Cross-refferai cjoff PVogramn Limes

cmd "X", target

target is either a basic reserved word (such as primt) or astring-literal. If it

is areserved word, it must not be enclosed in quotes; if it is astring-

literal, it must be enclosed In quotes.

104

fmmmMmmmmmmmmmmammmammmammammmmmmmmmmmm

This command finds all occurrences of areserved word or other string literal in

the resident program. The "finds" are listed on the display as five-digit line

numbers

To search for any basic reserved word (including reserved arithmetic operators),

use the keyword as-is. To search for anything else (including variable-names and

text), enclose the text inside quotes.

For example, suppose you have the following program in memory:

10 PRINT "THIS IS ATEST"

20 INPUT "PRESS <ENTER> FOR THE NEXT PRINT MESSAGE" 5Z$

30 A=A+1

40 PRINT "+++++++"

CMD "X" iPRINT will find all occurrences of print, except for cases where

print was part of aquoted string: lines 10 and 40.

CMD "X" >"PRINT" will find all occurrences of "print" as astring literal: line

20.

CMD ")!", +will list line 30, but CMD "X" ,"+"will list line 40. CMD "X" »

"A" will list lines 10, 20, and 30. Notice that variables and text are both treated

as string literals.

CMD "Z9?

Duplicate Output to Video and Printer

cmd"Z", "switch"

switch is either ow or off. switch must he enclosed in quotation marks.

llftigSiiiiligil^S^

This command enables or disables dual video/printer output. While the function

is "on," all video output is copied to the printer, and all printer output is copied

to the video. (The printer must be on-line when you turn dual output "on.")

Video and printer output may differ due to intrinsic differences in the printer and

video devices.

Examples

CMD "Z" >"ON"

Turns dual video/printer output on.

105

TRS-80 MODEL 111 DISH

CMD"Z"j "OFF"

Turns dual video/printer output off.

OFF FN

Delne Function

tie r-i nmthai'M '• rr~r<yi, ,.) =fan mlh

im Ian nam; ,si, rali !?isiaJ I@ name,

r'i "*- ni 'si

,-iv i,> r)* .i,i„iij in ./:

!!» ihat liie

tanclioa fioes.

Etis Minidia o: le u!i"-. !

'-< sign.

The deffn statement lets you create your own function. That is, you only

have to call the new function by name, and the associated operations will

automatically be performed. Once afunction has been defined with the deffn

statement, you can call it simply by inserting fn in front offunction name. You

can use it exactly as you might use one of the built-in functions, like sin, abs,

and strings.

The type of variable used for function name determines the type of value the

function will return. For example, if function name is single precision, then that

function will return asingle-precision value, regardless of the precision of the

arguments.

The particular variables you use as arguments in the def fn statement

(argument- 1, . . .) are not assigned to the function. When you call the function

later, any variable name of the same type can be used.

Furthermore, using avariable as an argument in adeffn statement has no effect

on the value of that variable. So you can use that particular variable in another

part of your program without worrying about interference from def fn.

The function can be defined with no arguments at all, if none are required.

For example:

DEF FNR =RND (90) +9

defines afunction to return arandom value between 10 and 99.

106

Examples

DEF FNR(AtB) =A+INK (B -(A -i>) *RND<0))

This statement defines function fnr which returns arandom number between

integers Aand B. The values for Aand Bare passed when the function is

"called," i.e., used in astatement like:

Y=FNR(R1 ,R2)

If ri and R2 have been assigned the values 2and 8, this line would assign a

random number between 2and 8to Y.

DEF FNL*<X) =STRING$(Xt "-")

Defines function fnl$ which returns a string of hyphens, xcharacters long.

The value for xis passed when the function is called:

PRINT FNL$(3)

This line prints astring of 30 hyphens.

Here's an example showing deffn used for acomplex computation —in

double-precision.

DEF FNX#(A*> B«) =(A* -B#) *(A# -B»)

Defines function fnx# which returns the double-precision value of the square of

the difference between a# and b#. The values for a# and b# are passed when

the function is called:

S# =FNX#(A#» B#)

We assume that values for a# and b# were assigned elsewhere in the program.

Sample Program

710 DEF FNM(T) =(1087 +S0R(Z73 +T))/1G,52

720 INPUT "AIR TEMPERATURE IN DEGREES CELSIUS"! T

730 PRINT "THE SPEED OF SOUND IN AIR OF" T"DEGREES

CELSIUS IS" FNY(T) "FEET PER SECOND,"

107

'""'--I

VUH TRS-80 MODEL Sii DISK SYSTEM

DEFUSE

Define Point of Entry for USR Routine

defusrw =address

nequals one of the digits 0, 1,...,S; if nis omitted, is assumed, address

specifies the entry address to amachine-language routine, address

must fee in the range [-32768,3275?!. address may be any numeric

expression or constant from -32718 to 32767.

defusr lets you define the entry points for up to 10 machine-language routines.

In non-Disk basic, the addresses were POKEd into ram. This poke method

cannot be used in Disk basic.

Examples

DEFUSR3 =&H7D00

assigns the entry point X'7D00', 32000 decimal, to the USR3 call. When your

program calls USR3, control will branch to your subroutine beginning at X'7D00\

DEFUSR =(BASE +1G)

assigns start address (base +16) to the usro routine.

Note: When decimal addresses are given, they are evaluated as signed two-byte

integers. So, for addresses above 32767, use desired decimal address -65536.

See usm«.

INSIR

Search for Specified String

instr (position, siring 1, string 2)

position specifies the position in string 1where the search is to begin.

position is optional; if it is not supplied, search automatically begins

at the first character in string 1. (Position 1is the first character in

string 1.)

108

*"iHftfe

:.__^_

...

.' 'illliP

sfr/flg Iis the string to lie searched.

string 2is the substring you want to search for.

This function lets you search through astring to see if it contains another string.

If it does, instr returns the starting position of the substring in the target string;

otherwise, zero is returned. Note that the entire substring must be contained in

the search string, or zero is returned. Also, note that instr only finds the first

occurrence of asubstring at the position you specify.

Examples

In these examples, a$ ="Lincoln":

INSTR(A*, "INC")

returns avalue of 2.

INSTR (A*» "12")

returns azero.

INSTR (A*. "LINCOLNABRAHAM")

returns azero. For aslightly different use of instr, look at

INSTR (3. "1232123" ,"12")

which returns 5

This program gets search and target text from the keyboard, then locates all

occurrences of the target text in the search text. Line 90 is just for "show."

10 CLEAR 1000

20 CLS

30 INPUT

40 INPUT

45 CLS

50 C=

SEARCH TEXT" iS$

TARGET TEXT"! T$

COUNT

:P=1'P =POSITION* C

60 F=INSTR(P»S$»T$)

70 IF F=THEN 120

80 C=C+1

90 PRINT i0,LEFT$(S$»F-l) +STRINGS (LEN( T$ ) , 191 )+

RIGHT* (S*»LEN(S$)-F-LEN(T$)+1)

100 P=F+LEN(T$)

110 IF P<= LEN(S$) -LEN(T*) +1THEN G0

120 PRINT "FOUND "i Ci "OCCURRENCES"

—HI

109

TRS-80 MODEL 111 DISK SYSTEM

LINE INPUT

Jfaiput aLine from Keyboard

line input "prompt" ;variable

prompt is aprompting message.

variable is the name that will be assigned to the fine you type in.

line input (or lineinput —the space is optional) is similar to input, except:

The Computer will not display aquestion mark when waiting for your

operator's input.

•Each line input statement can assign avalue to just one variable.

•Commas and quotes your operator can use as part of the string input.

•Leading blanks are not ignored —they become part of variable.

The only way to terminate the string input is to press (ENTER) .

line input is aconvenient way to input string data without having to worry

about accidental entry of delimiters (commas, quotation marks, colons, etc.).

The (EHTER) key serves as the only delimiter. If you want anyone to be able to

input information into your program without special instructions, use the line

input statement.

Some situations require that you input commas, quotes and leading blanks as

part of the data, line input serves well in such cases.

Examples

LINE INPUT A*

Input a$ without displaying any prompt.

LINE INPUT "LAST NAME) FIRST NAME? "5N$

Displays aprompt message and inputs data. Commas will not terminate the

input string, as they would in an input statement.

Sample Program

200 REM CUSTOMER SURVEY

205 CLEAR 1000

207 PRINT

110

ilL

210 LINE INPUT "TYPE IN YOUR NAME "5 A*

220 LINE INPUT "DO YOU LIKE YOUR COMPUTER? "5 B$

230 LINE INPUT "WHY? "5C$

235 PRINT

240 PRINT A$ iPRINT

250 IF B$ ="NO" THEN 270

260 PRINT "I LIKE MY COMPUTER BECAUSE "5 C$ ;END

270 PRINT "I DO NOT LIKE MY COMPUTER BECAUSE "5 C$

Notice that when line 210 is executed, aquestion mark is not displayed after the

statement, "Type in your name." Also, notice on line 230 you can answer the

question "Why" with astatement full of delimiters, commas and quotes.

Eeplace Portion of String

mids (iUsiring, position, length) =replacement-string

oldstring is the variable-name of the string you want to change.

position is tine ojimiSiic expression specifying the position of the first

character to be changed.

length is anumeric expression specifying the number of characters to be

replaced.

replacement-string is astring expression to replace the specified portion

of oldstring.

Note: If replacement-string is shorter than length-, then the entire repiacement-

string will tie used.

This statement lets you replace any part of astring with aspecified new string,

giving you apowerful string editing capability.

Note that the length of the resultant string is always the same as the original

string.

Examples

a$ ="Lincoln" in the examples below:

MID$(A$» 3, 4) ="12345":! PRINT A$

which returns LH234N.

111

IiS TOS-80 MODEL ill DISK SYSTEM

WHtKSBBSk^^

MID$(A$» 1tZ) ="": PRINT A$

which returns Lincoln.

MID$(A*» 5) ="12345": PRINT A$

returns lino 23.

MID$(A$, 5) ="01"; PRINT A$

returns lincoin.

HID$(A$» 1>3) ="*##": PRINT A$

returns ***coln.

Sample Program

770 CLS: PRINT: PRINT

7B0 LINE INPUT "TYPE IN AMONTH AND DAY MM/DD, "5 5$

790 P=INSTR(S$, "/")

800 IF P=THEN 780

B10 MID*(S*» Pt 1) =CHR*(45)

820 PRINT S$ "IS EASIER TO READ. ISN'T IT?"

This program uses instr to search for the slash ("/"). When it finds it

(if it finds it), it uses mid$ =to substitute a"—"(CHR$(45)) for it.

NAME

Eem?in1>b1fti eC'vjrireiiit Program

name newline, startline, increment

newiine specifies the new line number of the first line to be renumbered.

If omitted, 10 is used.

startline specifies the line number in the original program where

renumbering will start. If omitted, the entire program will be

renumbered.

increment specifies the increment to be used between each successive line

number. If omitted, 10 is used.

112

nj§§c HAe10

Examples

NAME

Renumbers the entire program: 10, 20, 30, . . .

NAHE 6000,5000 »100

Renumbers all lines numbered from 5000 up; the first renumbered line will

become 6000, and the following lines will be incremented by 100. All line

references within your program will be renumbered also.

USRm

Call to User's Exi ernal ^r broi tin 2

usr/j (nmexp)

where nspecifies one oS ten available usr calls, 0=0,1,2,. ..,9. If-ffis

omitted, zero is assumed.

nriiexp is an integer from -327S8 to 32757 and is passed as an integer

argument to the routine.

These functions (usro through USR9) transfer control to machine-language

routines previously defined with defusrjj statements.

When aurs call is encountered in astatement, control goes to the address

specified in the defusrtj statement. This address specifies the entry point to your

machine-language routine.

Note: If you call ausrh routine before defining the routine entry point with

DEFUSRn, an illegal function call error will occur.

You can pass one argument and retrieve one output value directly via the usr

argument; or you can pass and retrieve arguments indirectly via poke and peek

statements.

Example

1.0 DEFUSR1=&H7D00

20 REM,, .MORE PROGRAM LINES HERE

100 A=USR1(X)

The effect of this sequence is to:

113

si-Mi

Define usr as aroutine with an entry point at hex 7D00 (line 10).

2. Transfer control to the routine; the value xcan be passed to the routine if the

routine makes the call described below (line 100).

3. When the routine returns to basic, the variable Amay contain the value

passed back from the routine (if your routine makes the jump described

below); otherwise Awill be assigned the value of x(line 100).

Passing arguments to and from USR routines

There are several ways to pass arguments back and forth between your basic

main program and your usr routines: the two major ways are listed below.

1. poke the argument(s) into fixed ram locations. The machine-language routine

can then access these values and place results in other ram locations. When

the routine returns control to basic, your program can peek into these

addresses to pick up the "output" values. This Is the only way to pass two

or more arguments back and forth.

2. Pass one argument to the routine as the argument in the usRn call, then use

special rom calls to access this argument and return avalue to basic. This

method is limited to sending one argument and returning one value (both

are integers).

rom Calls

call 0A7FH Puts the usr argument into the hl register pair; Hcontains msb, l

contains lsb. This call should be the first instruction in your usr

routine.

jp 0A9AH Use this jump to return to basic; the integer in hl becomes the

output of the usr call. If you don't care about returning hl, then

execute asimple RETurn instruction instead of this jump.

Listed below is an assembled program to white out the display (an "inverse"

clear key!). Don't type it in. Type in the basic program that follows it.

7D00

3C00

00BF

03FF

00100 i

00110 ;zap OUT SCREEN USR FUt

00120 5

00130 ORG 7D00H

00140 5

00150 iEQUATES

001G0 !

00170 VIDEO E0U 3C00H

00180 WHITE E0U 0BFH

00190 COUNT EOU 3FFH

00200 9

5START OF VIDEO RAH

iALL WHITE GRAPHICS BYTE

?NUMBER OF BYTES TO MOVE

110 !PROGRAM CHAIN MOVES X'BF' INTO ALL OF VIDEO RAM

00220

114

DISK BASIC 1

"^'^wwiigg

7D00 21003C 00230 ZAP LD HL.UIDEO iSOURCE ADDRESS

7D03 3BBF 00240 LD (HL> .WHITE iPUT OUT 1ST BYTE

7D05 11013C 00250 LD DE.VIDEO+1 .DESTINATION ADDRESS

7D0B 01FF03 002B0 LD BC, COUNT .NUMBER OF ITERATIONS

7D0B EDB0 00270

00280 .

LDIR .DO IT TO IT! ! !

7D0D C9 00290 RET 5RETURN TO BASIC

7D00 00300 END ZAP

This routine can be POKEd into ram and accessed as ausr routine. First start basic and answer the

MEMORY SIZE question with 31993. Then run the program.

100 'PROGRAM: USR1

110 'EXAMPLE OF AUSER MACHINE LANGUAGE FUNCTION

115 'DEPRESS THE '1' KEY WHILE NUMBERS ARE PRINTING TO STOP

120 '

130 '******* POKE MACHINE PROGRAM INTO MEMORY *******

140 '

150 DEFUSR1 =&H7D00

160 FOR X=32000 TO 32013 '7D00 HEX EQUAL 32000 DECIMAL

170 READ A

180 POKE X» A

190 NEXT X

192 '

194 '******* CLEAR SCREEN &PRINT NUMBERS 1THRU 100 *******

19G '

200 CLS

205 PRINT TAB (15)? "WHITE-OUT USER ROUTINE": PRINT

2i0 FOR X=1TO 100

220 PRINT X!

225 A$ =INKEY*: IF A$ -"@" THEN END

230 NEXT X

240 '

250 '******* JUMP TO WHITE-OUT SUBROUTINE *******

260 '

270 X=USR1 (0)

280 FOR X=1TO 1000: NEXT X'DELAY LOOP

290 GOTO 200

300 '

310 '******* DATA IS DECIMAL CODE FOR HEX PROGRAM *******

320 '

330 DATA 33.0.60,54.191 .17.1 .60.1 .255. 3,237.176,201

Run the program. An equivalent basic white out routine takes along time by comparison!

115

Disk-Related Features

Disk basic provides apowerful set of commands, statements and functions

relating to disk i/o under trsdos. These fall into two categories:

1. File manipulation: dealing with files as units, rather than with the distinct

records the files contain.

2. File access: preparing data files for i/o; reading and writing to the files.

Under the heading, File Manipulation, we will discuss the following

commands.

Delete aprogram or data file from the disk

Load abasic program from disk

Merge an Ascii-format basic program on disk with one

currently in ram

Load and execute abasic program stored on disk

Save the resident basic program on disk

Under the heading, File Access, we will discuss the following statements and

functions.

kill

load

MERGE

run "program"

save

Statements

OPEN

INPUT #

LINE INPUT#

PRINT#

HELD

GET

PUT

LSET

RSET

Functions

CVD

CVI

CVS

EOF

LOC

Open afile for access (create the file if necessary)

Close access to the file

Read from disk, sequential mode

Read aline of data, sequential mode

Write to disk, sequential mode

Assign field sizes and names to random-access file buffer

Read from disk, random access mode

Write to disk, random access mode

Place value in specified buffer field, add blanks on the

right to fill field

Place value in specified buffer field, add blanks on the left

to fill field

Restore double-precision number to numeric form after

GETting from disk

Restore integer to numeric form after GETting from disk

Restore single-precision number to numeric form after

GETting from disk

Check to see if end of file encountered during read

get current record number.

116

lof Return number of last record in file

mkd$ Convert double-precision number to string so it can be put

on disk

mki$ Convert integer to string so it can be put on disk

mks$ Convert single-precision number to string so it can be put

on disk

117

JS TBS-80 MODEL 111 DBSK SYSTEM

Fie Manipulation

KILL

Delete aFie from the Disk

kill exp$

exp$ defines afile specification far an existing file.

This command works like the trsdos kill command —see trsdos Library

Commands.

Example

KILL"0LDFILE/BAS.PSW1"

deletes the file specified from the first drive which contains it.

Do not kill an open file, or you may destroy the contents of the diskette. (First,

close the open file.)

LOAD

Load BASIC Program File from Disk

torn exfl${fil

where exp$ defines afilsspec for abasic program file stored on disk.

r\h^: b,„' *s bbs i*. the program afti ii! is loaded.

This command loads a basic program file into ram; if the roption is used,

basic will proceed to run the program automatically; otherwise, basic will

return to the command mode.

118

i^pifiiiiMl

Ha^i^MPin

&miB&*®ttia&m&8&sfflNat&i&

load without the roption clears all variables and closes all open files, load

with the roption clears all variables but does not close the open files.

load with the roption is equivalent to the command run exp$,K. Either of

these commands can be used inside programs to allow program chaining —one

program calling another, etc.

Example

L0AD"PR0G1/BAS:2"

Clears resident basic program and loads progi/bas from Drive 2; returns to

basic command mode.

am wltt Resideii rProi

MERGE eXBS

exp $is fiif'- specification for a

sawed witi the a option.

\u,i''if MJi «r

I I if, e.g., ^rograu

merge is similar to load —except that the resident program is not erased before

the new program exp$ is loaded. Instead, the new program is merged into the

resident program.

That is, program lines in exp$ will simply be inserted into the resident program

in sequential order. If line numbers in exp$ coincide with line numbers in the

resident program, the resident lines will be replaced by those from exp$.

119

TRS-80 MODEL ill DISK SYSTEM

Program on Disk Program in Ram Merged Program in R

10 10

20 20

30 30

40 40

50 50

60 60

70 70

90 90 j90

100 100

110 110

120 120

Sample Use

Save this program in ascii format.

1000 REM .,,SUBROUTINE TO BAY HELLO

1010 PRINT "HELLO!"

1020 RETURN

Type NEW (ENTER) ,then type in this program.

100 CLB

110 PRINT "LET'S CALL THE SUBROUTINE .,"

120 PRINT "DIALING NOW ,,,"

,130 FOR 1=1TO 1000 ;NEXT

140 GOSUB 1000

150 PRINT "BACK FROM SUBROUTINE."

160 END

Now type MERGE "file" using the file name given to the first file. List the program. Then run it.

[6 £199

Load and Execute aProgram from Disk

run ft7e[.Rl

file is the name *tJ abasic program file. II ,$ ndnng expression. (If astring

constant is used, it must be enclosed mquotes.) The ,r option causes

basic to leave open files open. If omitted, open files are closed before

the program Is run.

120

This command loads and executes abasic program stored on disk. It may be

used inside aprogram to allow chaining (one program calling another).

Examples

RUN "PROG"

Loads and executes prog (all open files are closed first).

A$="NEWPRGG"

RUN A$ >R

Loads and executes newprog (all open files remain open).

iave rrogn

save file [,a]

tile is the name of abasic program file. If is astring expression.

(If astring constant 1? ised, ii must be sncBosed in quotes

)

acause:, the file to be stored In asm ra ffier than compresses! format.

This command lets you save your basic programs on disk. You can save the

program in compressed or ascii format.

Using compressed format takes up less disk space and is faster during both

saves and loads. Using the ASCII option makes it possible to do certain things

that cannot be done with compressed format basic files. \A

For example:

8The merge command requires that the disk file be in ascii form.

V/vr

Programs which read in other programs as data will typically require that the /xJp

data programs be stored in ascii.

•The trsdos command append also requires that disk files be in asch form.

121

TRS-80 MODEL ISi DISK SYSTEi

Examples

SAUE"FILE1/BAS. J0HN0D0E:3"

saves the resident basic program in compressed format with the file name filei ,

extension /bas, password johnqdoe; the file is placed on Drive :3.

SAVE"MATHPAK/T>!T" .A

saves the resident program in ascii form, using the name mathpak/txt, on the

first nonwrite-protected diskette.

Upon completion of asave, basic returns in the command mode.

122

^m^mmmmmmmsm

>r<1^. Access

This section is divided into four parts:

Creating files and assigning buffers —open and close

2. Statements and functions

3. Sequential i/o techniques

4. Random i/o techniques

If this is your first experience with disk file access, you should concentrate on

parts 1,3and 4, perhaps just skimming through part 2to get ageneral idea of

how the functions and statements work. Later you can go back to part 2and

learn the details of statement and function syntax.

Creating Fies and Assigning Buffers

During the initialization dialog, you type in anumber in response to how many

files? The number you type in tells basic how many buffers to create to handle

your disk accesses (reads and writes).

Each buffer is given anumber from 1to 15. If you type:

HOW MANY FILES? 3V (MM)

basic sets aside 3buffers, numbered 1,2,3.

You can think of abuffer as awaiting area that data must pass through on the

way to and from the disk file. When you want to access aparticular file, you

must tell basic which buffer to use in accessing that file. You must also tell

basic what kind of access you want —sequential output, sequential input, or

random input/output.

All this is done with the open statement, and "undone" with the close

statement.

OPEN

Dpd bi aFie

qpem made, buffer, file record lengih

modie is aits ii ig iicpression contain! i*one of the toitowii g:

iSepi itia impmi sta rii ii ia! the first iee§ rd If She lite is in i' hi *i

ii will be sm&M'L

mmm

123

.feaSfeel '-

;.j

oSequential oytput starting at the first record. IS the file is not

found, it will -be created.

e(Extend) Sequential output starting at end of file, if the file is not

found, it will be created.

'theifile is not found, it will be created.

rRandominpui/output,

IS modeM aconsta it, ?! must be enclosed in poles, coois be avab-iabcc /

buffer is anumeric expression specifying which buffer is to be used.

file is astring expression containing the file specification. If aconstant is as a<5o vC P

used, it must be enclosed in quotes.

nsmi-lengii is &numeric expression from to 2§§ specifying the logical

record length. II

>5 the same as 256. This option may only be used if

rariable-lengfh records were requested during initialization (How

Many Files?). If record-length is omitted, 256 is used, record-length

is used with Random access only.

This statement lets you create afile, write data into it, update it, and read it. For

details on file access, see Methods of Access later in this section.

If file includes adrive specification/ basic will use only the specified drive. If

no drive is specified, basic will search for amatching file, starting with the

master drive (usually Drive 0).

Examples

OPEN "0" i1>"DATAFILE"

Opens datafile (creates it if it doesn't already exist) for sequential output.

Output will be done through buffer #1 .Records will be 256 bytes long. Since

the "o" mode is specified, output will start at the first record in the file.

If "e" is used instead of "o", output will start at the end of the file.

OPEN 'PAYROLL/A:!" »G4

Opens/creates payroll/a for random input/output. Access will be through

buffer #2. Records will be 64 bytes long (if basic was initialized for variable-

length records). &€lo\\X> i.e.k)QTO

BUFFER =3: FILE* ="DATA"

OPEN "R"» BUFFER. FILE$» RECL

RECLN =128 Li stcxoe.

Opens/creates data for random input/output. Access will be through buffer #3.

Records will be 128 bytes long (if basic was initialized for variable-length

records).

124

,i$ **wsi

:J[_

^'Ipglppb

ii^Bt

^KfflP >'iJllilS$liSfifiiIBifP?

Close Access to the Fie

close [nmexp [, nmexp. ,.] ]

/i.T/exp has avalue from 1to 15, and refers to the file's buffer number

(assigned when the file was opened). If nmexp Isunified, all §p@i

files will be closed.

This command terminates access to afile through the specified buffer(s).

If nmexp has not been assigned in aprevious open statement, then

close nmexp

has no effect.

Examples

CLOSE 1,2,8

Terminates the file assignments to buffers 1, 2and 8. These buffers can now be

assigned to other files with open statements.

CLOSE FIRST'Z +COUNT/f.

Terminates the file assignment to the buffer specified by the sum

(first% +COUNT%).

Do not remove adiskette which contains afile openedfor writing (mode —O,

E, or R). First close the file. This is because the last 256 bytes of data may not

have been written to disk yet. Closing the file will write the data, if it hasn't

already been written.

Any modification to the resident program (new, editing, load, merge, etc.)

will cause open files to be closed.

125

30DEL 111 DISK SYST1

INPUT#

Seep etial

]

2>ii from Disk

ihput# nmexp, !/ar[,rar. J

where /fme^p specifies asequential input file buffer, nmeifi=t,2,. ,,11.

sot is the variable name to contain the data ffroj-* the file.

This statement inputs data from adisk file. The data is input sequentially. That

is, when the file is first opened, apointer is set to the beginning of the file.

Each time data is input, the pointer advances. To start over reading from the

beginning of the file, you must close the file and re-open it.

input# doesn't care how the data was placed on the disk —whether asingle

print# statement put it there, or whether it required 10 different print#

statements. What matters to input# are the positions of the terminating

characters and the eof marker.

To input# data successfully from disk, you need to know ahead of time what

the format of the data is. Here is adescription of how input# interprets the

various characters it encounters when reading data.

When inputting data into avariable, basic ignores leading blanks; when the

first non-blank character is encountered, basic assumes it has encountered the

beginning of the data item.

The data item ends when aterminating character is encountered or when a

terminating condition occurs. The particular terminating characters vary,

depending on whether basic is inputting to anumeric or string variable.

Special Note

Here's an important exception to keep in mind in reading the following material.

When OTTER) (a carriage return) is preceded by &(a line feed), the OTTER) is

not taken as aterminator. Instead, it becomes apart of the data item (string

variable) or is simply ignored (numeric variable).

To enter the OTTER) character, press OTTER) .)

This exception applies to all cases noted below where OTTER) is said to be a

terminator.

126

IL#i^if\ PMQly

Suppose the data image on disk is

1.234 -33 27 (ElTEfD

[ENTER) denotes acarriage-return character (ascii code decimal 13).

Then the statement

INPUT«i ,A,B»C

or the sequence of statements

INPUT#i .A: INPUT*! »B: INPUT#1 ,C

will assign the values as follows:

A=1.234

B=-33

C=27

This works because blanks and (EMTER) serve as terminators for input to numeric

variables. The blank before 1.234 is a"leading blank," therefore it is ignored.

The blank after 1.234 is aterminator; therefore basic starts inputting the second

variable at the -character, inputs the number -33, and takes the next two

blanks as terminators. The third input begins at the 2and ends with the 7.

String Input

When reading data into astring variable, input ignores all leading blanks;

the first non-blank character is taken as the beginning of the data item.

If this first character is adouble-quote ("), then input will evaluate the data as

aquoted string: it will read in all subsequent characters up to the next double-

quote. Commas, blanks, and (ENTER)characters will be included in the string.

The quotes themselves do not become apart of the string.

If the first character of the string item is not adouble-quote, then input will

evaluate the data as an unquoted string: it will read in all subsequent characters

up to the first comma, or (ENTER) .If double-quotes are encountered, they will be

included in the string.

For example, if the data on disk is:

PECOS, TEXAS "GOOD MELONS"

Then the statement

INPUT*! iA$ ,B$ ,C$

127

would assign values as follows:

A$ =PECOS

B$= TEXAS "GOOD MELONS"

C$ =null string

If acomma is inserted in the data image before the first double quote, c$ will

get the value, good melons.

These are very simple examples just to give you an idea of how input works.

However, there are many other ways to input data —different terminators,

different target variable types, etc.

Rather than taking ashotgun approach and trying to cover them all, we'll give a

generalized description of how input works and what the terminating characters

and conditions are, and then provide several examples.

When basic encounters aterminating character, it scans ahead to see how many

more terminating characters it can include with the first terminator. This ensures

that basic will begin looking for the next data item at the correct place.

The list below defines the various terminating sets input# will look for. It will

always try to take-in the largest set possible.

Numeric-input terminator sets

end of file encountered

255th data character encountered

,(comma)

(Ml

(ESTER) ©

[...] [(ENTER) ]

Quoted-string terminator sets

end of file encountered

255th data character encountered

"(double quote)

"[ •••][,]

"[...][ (ENTER)!

"[...nun©©]

Unquoted-string terminator sets

end of file encountered

255 th data character encountered

(ENTER) r©1

Figure 13 describes how input# assigns data to avariable.

wmm

128

iaHHnHnB9Bfnsi WB9BSH lifci

mfflEnB?

_±_

EXAMINE NEXT

CHARACTER

IGNORE IT £PICKUP THE

TERMINATOR

SET

GET DATA FROM

TEMPORARY

SAVE AREA

PUT IT INTO

TEMPORARY

SAVE AREA

EVALUATE IT

EXAMINE NEXT

CHARACTER

ASSIGN TO

""?" VARIABLE

Figure 13. Input process.

The following table shows how various data images will be read-in by the

statement:

INPUTsl »A,B»C

Ek.# Image on disk

123.45 [EWTEffi ^l 8.2E4 7000 (EWTlER)

t».2,3»4 (INTER)

l>3 »eof

Values

assignee!

A= 123.45

B=82000

C=7000

A=34

B=5

A=1

C=2

A=1

B=3

C=eof error

(eof =end of file):

In Example 2above, why does variable cget the value 0? When the input

reaches the end of file, it terminates that last data item, which then contains

"A12." This is evaluated by aroutine just like the basic val function —which

returns azero since the first character of "A12" is anon-numeric.

t.^iV'V.;'^

129

IS-80 MODEL 11! USE SYSTEM

In Example 3, when input# goes looking for the second data item, it

immediately encounters aterminator (the comma); therefore, variable Bis given

the value zero.

The following table shows how various data images on disk will be read by the

statement:

INPUT#1 »A$.B$

Imageon disk

'ROBERTS .J."ROBERTS »M ,Neof

ROBERTS. J. tROBERTS. M.N. (ENTER)

THE WORD "QUO" .12345,789 (MM

Values assigned

A$:ROBERTS,J.

B$:ROBERTS,M.N.

A$:ROBERTS

B$:J.

A$:THE WORD "QUO,:

B$: 12345. 789

A$:BYTE©(HTiB)

UNIT OF MEMORY

B$:nu)l (eof error)

In Example 3, the first data item is an unquoted string, therefore, the double-

quotes are not terminators, and become part of AS.

In Example 4, the (EiTER) is preceded by an &, therefore it does not terminate

the first string; both &and fEMTER)are included in a$.

LINE INPUT#

Read aLine of Text from Disk

line mpin#nmes[fi,vat$

where nmexp specifies asequential output file buffer, nmexp =1,2,... ,15.

var$ is the variable name to contain the string data.

Similar to line input from keyboard, this statement reads a"line" of string

data into var$. This is useful when you want to read an Ascn-format basic

program file as data, or when you want to read in data without following the

usual restrictions regarding leading characters and terminators.

130

DISK BASIC

line input (or lineinput —the space is optional) reads everything from the first

character up to:

an (ENTER) character which is not preceded by &

2. the end of file

3. the 255th data character (this 255 character is included in the string)

pairs —are included in the string.

For example, if the data looks like:

10 CLEAR 500 (ENTER)

20 OPEN" I" »1 *"PR0G" (EJUS)

then the statement

LINEINPUTttl ,A$

could be used repetitively to read each program line, one line at atime.

PEINT#

5s fltin ^iiWn its idDi kFife

mm#nmexp, [using formats;] exp[p exp. ..]

where nmexp specifies asequential output file buffer, nmexp= 1,2, ...,15.

formats is asequence of field specifiers used with the using option.

Fis adelimiter placed ijetween every two expressions to be PRimed to disk;

either asemi-colon or comma can be used (semi-colon is preferable).

exp is the expression to he evaluated and written to disk.

This statement writes data sequentially to the specified file. When you first open

afile for sequential output, apointer is set to the beginning of the file, therefore

your first print# places data at the beginning of the file. At the end of each

print# operation, the pointer advances, so the values are written in sequence.

mmm

131

'H TRS°80 MODEL US DiSK SYSTEM

Aprint# statement creates a disk image similar to what aprint to display

creates on the screen. Remember this, and you'll be able to set up your print#

list correctly for access by one or more input statements.

print# does not compress the data before writing it to disk; it writes an ascii-

coded image of the data.

For example, if A=123.45

PRINT#1 »A

will write anine-byte character sequence onto disk:

123.45 (ENTER)

The punctuation in the print list is very important. Unquoted commas and semi-

colons have the same effect as they do in regular print to display statements.

For example, if A=2300 and b=1.303, then

PRINT#1 »A»B

places the data on disk as

2300 1,303 (HUB)

The comma between Aand bin the print# list causes 10 extra spaces in the

disk file. Generally you wouldn't want to use up disk space this way, so you

should use semi-colons instead of commas.

PRINT*! »A!B

writes the data as:

2300 1.303 (ENTER)

print# with numeric data is quite straightforward —just remember to separate

the items with semi-colons.

print# with string data requires more care, primarily because you have to insert

delimiters so the data can be read back correctly. In particular, you must

separate string items with explicit delimiters if you want to input# them as

distinct strings.

For example, suppose:

A*="J0HN 0. DOE" andB*="100-01-001"

Then:

PRINTbI >A*»B*

would produce this image on disk:

JOHN 0. DOE100-01-001 (ENTER)

which could not be input back into two variables.

The statement:

132

ISK BASIC

www

PRINTttl .A$5" »"5B*

would produce:

JOHN 0, DOE. 100-01-001

which could be input# back into two variables.

This method is adequate if the string data contains no delimiters —commas or

(ENTER) —characters. But if the data does contain delimiters or leading blanks

that you don't want to ignore, then you must supply explicit quotes to be written

along with the data. For example, suppose A$ ="DOE .JOHN 0." and B$ ="100

-01-001"

If you use

PRINT*

.A$i" »"SB$

the disk image will be:

DOE. JOHN 0, .100-01-001 (ENTER)

When you try to input this with astatement like

INPUT#2.A$.B$

A$ will get the value doe, and b$ will get john q. —because of the comma after

doe in the disk image.

To write this data so that it can be input correctly, you must use the chrs

function to insert explicit double quotes into the disk image. Since 34 is the

decimal ascii code for double quotes, use chr$(34) as follows:

PRINT*1 »CHR$(34) iA$!CHR$(34) !B$

this produces the disk image

"DOE. JOHN Q, "100-01-001 CENTER)

which can be read with asimple

INPUT«2.A$B$

Note: You can also use the chrs function to insert other delimiters and control

codes into the file, for example:

chr$(13) carriage return ((ENTJR)character)

chr$( n)or chr$( 12) line-printer top-of-form

USING Option

This option makes it easy to write files in acarefully controlled format.

For example, suppose:

A$="LUDWIG"

133

;;•-•;- •!S-80 MODEL 111 DISK SYSTEM

IMP"1""

B*="VAN"

C$="BEETHOMEN"

Then the statement

PRINT«i tUSING"! ,!, 1Z" 5A*5B*5Ct

would write the data in nickname form:

L.U.BEET <ENTER)

(In this case, we didn't want to add any explicit delimiters.) See the print using

description in the level hbasic Reference Manual for acomplete explanation of

the field-specifiers.

Random Access Statements

FIELD

Organize aRandom File-Buffer into Fields

field nmexp,nmexp1 Asvart$[,nmexp2 as var2$. ..]

nmsxp specifies arandom access fife buffer, w/nejr/?=1,2,...,15.

nmsKfi speslfiss the length of the first field.

var1$ defines avariable name for the first field.

mr,exB2 specifies the length of the second field.

var2$ defines avariable name for the second field.

...Subsequent nmexpks, var$ pairs define other fields in the buffer.

Mote: The sum of all the field-Iangths must not exceed the record length, and

should equal the record length.

Before FiELDing abuffer, you must use an open statement to assign that buffer

to aparticular disk file (you must use random access mode). Then use the field

statement to organize arandom file buffer so that you can pass data from basic

to disk storage and vice-versa.

Each random file buffer has up to 256 bytes which can store data for transfer

from disk storage to basic or from basic to disk. (When variable-length files are

used, maximum may be from 1to 256.) However, you need away to access this

134

SsiC

buffer from basic so that you can either read the data it contains or place new

data in it. The field statement provides the means of access.

You may use the held statement any number of times to "re-organize" afile

buffer. FiELDing abuffer does not clear the contents of the buffer; only the

means of accessing the buffer (the field names) are changed. Furthermore, two

or more field names can reference the same area of the buffer.

Examples

FIELD 1>128 AS A$ ,123 AS B$

This statement tells basic to assign the first 128 bytes of the buffer to the string

variable a$ and the remaining 128 bytes to b$. If you now print a$ and b$, you

will see the contents of the buffer. Of course, this value would be meaningless

unless you have used get to read a 256-byte record from disk.

Note: All data —both strings and numbers —must be placed into the buffer in

string form. There are three pairs of functions (mki$/cvi,mks$/cvs,mkd$/cvd)

for converting numbers to strings and vice- versa. See "Functions" below.

FIELD 3. IB AS NH$ ,25 AS AD$ »10 AS CY$ ,2AS ST$ HAS ZP$

The first 16 bytes of buffer 3are assigned the buffer name nm$; the next 25,

ads; the next 10, cy$; the next 2, st$ and the next 7, zp$. The remaining 196

bytes of the buffer are not fielded at all.

Radio Shack Hardware Manual 3 Disk System Owners 1980 Tandy A Text

Navigation menu

Versions of this User Manual:

Views

Navigation