Radio Shack TRS-80 User manual

ladle IhaeN
TRS-SO @) ModelII
Disk Operating System
Reference Manual
ADescription of the Operating System:
General Information, Operator Commands,
Technical Information
CUSTOM MANUFACTURED IN THE U.S.A. BY RADIO SHACK ~ ADIVISION OFTANDY CORPORATION

Section 0
New Release Update
TRSDOS 2.0
This sectionpertainsto the latestrelease of TRSOOS. It describes important
operations
you should perform before beginning any specific application. It
alsosummarizesthe
changes and improvements contained in this version
OfTRSOOS.
Before attempting to follow any operationsgiven in thissection, you should
read Section 1. Fordetailson programs or utilitiesmentioned, see the
specific entryforthat subject (use the Index).
Important
Do not tryto use 1.1 or 1.2diskettes when the system is running under 2.0;
do not tryto use 2.0 diskettes when the system is running under 1.1/1.2.
Either case could destroy the information on the diskette. 1.1/1.2 diskettes
must be converted to 2.0, as explainedin this section.
NewCustomers:
Ignorethe references to TRSOOS 1.1/1.2; these are forcustomers who are
upgrading to 2.0.

OOEL II TRSOOS
ImportantDiskOperations
In this section, we will outline some things you should do before you begin any
applications with TRSDOS:
1. Initialize Some New Diskettes (FORMAT)
2. Duplicate the TRSDOS Diskette (BACKUP)
3. Make aWorking Master(PURGE)
4. Upgrade Diskettes from Previous Versions (XFERSYS)
You will need to use several TRSDOS commands and utility programs. In this
section we will list thembriefly. For details, see the full descriptions elsewhere in
this manual (use the Index).
1. Initialize SomeNew Diskettes (FORMAT)
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.
The FORMAT utility program performs this function. We suggest you format several
diskettes now. You cannotperform the otheroperations listed in this section until
you have done this.
StartTRSDOS as explainedin Chapter
1, then type in acommand like this:
FORMAT :d
where dis one ofthe drives in your system.
The Computerwill prompt you to mount the diskette for formatting.
If you are formatting in drive 0, you must remove the TRSDOS disketteand insert
the disketteto be formatted.
The resultant formatted diskette will have the name TRSDOS and password
PASSWORD. Fordiskettes that will contain TRSDOS, we suggest you use these
default values.
For your datadiskettes, use any diskette name (ID =name) and any
password
(pw =password).
See FORMAT for further details.
36

VERSION 2.0 UPDATE
2. Duplicatethe TRSDOS 2.0Diskette
(BACKUP)
Use your factory-release TRSDOS diskette for one purpose only-as an "original
master" .It should not be used for applications, only for creating a" working
master". You canthen make changes to the working masterto suit various
applications.
As an added precaution, keep the factory-release diskette write-protected.
Note: In the BACKUP dialog, the term" source diskette" refers to the diskette to be
duplicated; "destination diskette" refers to the diskette to contain the copy of the
original.
UnderTRSDOS READY, type in the appropriate BACKUP command. We suggest the
following:
BACKUP 0 TO destination
wheredestination is the drive containingthe formatted diskette which will become
a TRSDOS diskette.
If destination =0, TRSDOS will prompt you when to swap source and destination
diskettes.
When the backupprocess is complete, remove the original diskette. Keep it in a
safe place and don't use it unless you need to recreate the working master.
3. MakeaWorkingMaster (PURGE)
The factory-release TRSDOS diskette contains avariety of non-essential files. These
non-essential files serve various purposes, including:
•Demonstration of programming techniques
•Modification of system input/outputsoftware
•Special features and functions
Now that youroriginal TRSDOS diskette is safely set aside, you should create one or
more customized system diskettes to suit your needs. For adiscussion of' 'full
system", "minimum system" , and' 'data" diskettes, see Disk File
Requirements later in this section.
Determine whatfiles you will need for day-to-day use. You may want to have
several different systemdiskettes-each with adifferent collection of system files.
If there are some files you don't want on any of yourworking diskettes, you may
delete themfrom the working master. Ifthere are files you don't want in aparticular
application, delete them from that diskette only.
To delete files, use the PURGE command.
37

MODEL II TRSDOS
PURGE
UNWANTED FILES
FILES NOT
NEEDED FOR
THIS APPLICATION
SPECIAL
APPLICATIONS
SYSTEM
STEPS FOR CREATING AWORKING MASTER IBI
AND ASPECIAL APPLICATION DISKETTE lei
Here are the files included on the factory release TRSDOS 2.0 Diskette:
SYSTEM/SYS
This file is required on all TRSDOS diskettes. Do not purge it if you wish to use the
diskette in drive O.
SYSRES/SYS
This file is required on all full system diskettes, but not on minimum systems. (To
find definitions, use the Index.) If you want to use the diskette to start TRSDOS, do
not purge this file.
BACKUP, PATCH, XFERSYS, FORMAT, TERMINAL,
MEMTEST, BASIC
These important systemfiles should be kept on your working master. The purpose
of each file is listed elsewhere in this manual (see entries in the Index). After you
understand the purpose of each file, you may elect to delete any or all of them for
specialized purposes.
38

VERSION 2.0 UPDATE
SYSTEM64and SYSTEM32
Only one of these two is needed in yoursystem. If you have a 64K RAM system, keep
SYSTEM64 and delete SYSTEM32; if you have a 32K RAM system, keep SYSTEM32 and
delete SYSTEM64.
We will referto the remaining file as SYSTEMnn. nn == 32 or 64, depending on
which one you kept.
SYSTEMnn contains the high-memory routines for: HOST, SPOOL, SETCOM and all
serial110, DO and DEBUG. You should keep this file on your working master. If you
have an application which will notrequire any of the above-listed capabilities, you
may delete it.
HERZ50, LPII, PRTBKSP
Theseare Do-files which allow you to make specific changes or' 'patches" to
systemfiles. See HERZ50, LPn and PRTBKSP for descriptions. If you don't need to
make any of these changes, you may delete these files from yourworking master.
Or if you do need to make them, delete them after they are used.
DOCOMnn, BASCOMnn, COMSUBnn, EXDATMnn,
DATMnn (nn =32 or64)
These are demonstration programs androutines. Seethe descriptions elsewhere in
this manual (use the Index).
For each file, there is a 32K RAM and a 64K RAM version. You should keep the
version that matches your system's RAM size and deletethe other.
These files are for demonstration and incidental purposes only. You may delete any
or all of them from your working master, depending upon your needs.
(Programmers should study how they work, to gain insights into techniques for
using TRSDOS.)
4. UpgradeDiskettesfrom Previous Versions
(XFERSYS)
This section applies onlyto customers who have been using aprevious version of
TRSDOS. New customers may skip it.
All diskettes ~ ,'system" and" data',- must be converted before they can be
used underTRSDOS 2.0. The XFERSYS utility program does this for you. Attempts to
use un-converted 1.2 diskettes under2.0 may destroy the information on the
diskettes.
See XFERSYS for the proper procedures to upgrading adiskette. Follow them
carefully!
39

MODEL II TRSDOS
DiskFile Requirements
There are three general configurations of diskettes that may be used in the TRSDOS
system:
•Full system - The factory release copy of TRSDOS for use in drive o.
• Minimum system - May be used in drive 0afterinitialization.
•Data- May only be used in drives 1,2 and 3.
"Full System"
This is adiskette which can be usedto start (' 'bootstrap' ') the operatingsystem and
performall the library commands, utilities, and supervisorcalls. The factory
release copy ofTRSDOS is afull system.
Thefull systemcontains many files which will not be needed for day-to-day
applications- but which may come in handy every now and then. Forthis reason,
you should always keep yourfactory release version
ofTRSDOS intact, and use a
backupcopy as aworking master.
Whyand How of FullSystemDiskettes
If you have aDiskExpansion Unit, you will probably find it mostconvenient to
have aFull SystemDiskette in drive 0at all times. This will give you access to all
of
the utilities and systemfunctions without adisk swapbeing necessary. For most
applications, there is still plenty
of roomleft on afull system diskette for program
storageand for small to medium sized data files. Largerdatafiles may be stored on
datadiskettes in the Disk Expansion Unit.
Itis faster, by the way, to
put differentfiles or programs being accessed at the same
time on different drives since, in most cases, the drive seek time will be reduced.
On each drive, the read/write head will usually be closerto the desired location of
thefile ~urrently being accessed. Using CREATE before building the datafile will
help insure thatthe file will be stored in alarge block
of contiguous storage on
diskette. This will also help speed up disk accesses.
The working masterthat you create will be afull system diskette. The original
masteris also afull system diskette and both should be kept that way.
40

/~-"
VERSION 2.0 UPDATE
"Minimum System"
This is adiskette which cannot be used to startTRSDOS, but may be used after the
systemis fully initialized. This diskette contains the minimum amount
of system
files required for TRSDOS operationafter initialization.
You may want to create aminimum system diskette for use in special applications
where space in drive 0is at apremium. You may use PURGE
or XFERSYS to create a
minimum system.
Whyand How of MinimumSystem Diskettes
If you don't have aDiskExpansion Unit, but still need extradisk space for storage
oflarge data or programfiles, you may ~eed to create minimum system diskettes
for use. This kind
of diskette has the minimumoperating system programs on it for
processing, but may not be used for resetting orstarting up. These diskettes may
only be used in drive 0afteryou have reset or started using afull system diskette.
The minimum systemdiskette will contain the following system programs:
SYSTEM/SYS
SYSTEMnn (nn =32 for 32K machines, 64 for 64K machines)
Note: If you do not planto use DO, HOST, SPOOL, DEBUG, orserial I/O during the
execution
of yourapplication, you will not need SYSTEM 64 orSYSTEM 32 on your
minimumsystem diskette.
The technique for using aminimum systemdiskette
is as follows:
1. Initialize using yourworking master (which must be afull system diskette).
2. Remove this diskette from drive 0and replace with the minimum system
diskette that you have created.
3. Now you may startrunning yourapplication which should be on the minimum
systemdiskette.
If your application requires more than one diskette for the storage of files or
programs, then eachdiskette used (with yourone-drive system) should be a
minimumsystem. Yourapplication should be written such that you only have files
openon the diskette that is currently in drive 0, and that when you need to swap
diskettes to get data (orprograms) from anotherminimum system diskette, that you
close the openfiles, then do the swap, then open the file(s) that you need from the
otherdiskette.
You may also use minimum system diskettes in amulti-drive setup, but keep in
mind that you must start
or reset with afull system diskette in all cases.
ToCreateaMinimumSystemDiskette
There are two ways to create aminimumsystem disk. The first is to start with a
copy
of eitheryour working master or any otherfull system disk and, from this,
purge
off all of the modules except SYSTEM/SYS and SYSTEM64 (orSYSTEM32). The
41

MODEL II TRSDOS
other way to create aminimumdiskette is to use XFERSYS with the MIN option. This
will purge
off all of the unnecessary modules and will also purge off SYSTEM64
(and/or SYSTEM 32). If you plan to use DO, HOST, serial 110, DEBUG, or SPOOL in
yourapplication, then you should use
the' 'manual" method using PURGE.
"Data"
This is adiskette which does not have the minimum system file requirement, and
therefore may only be used in the external drives
(1,2 and 3). Such diskettes have a
maximum
of space available for user files.
Whyand How of Data Diskettes
If you have aDiskExpansion Unit, and you plan to run applications or programs
that require large datafiles, you will want to have available as much disk space as
possiblefor the storage
of the file(s) or program(s). In this case, you will not need
any
of the operating systemprograms on such adiskette. While this kind of diskette
may notbe used atany time in drive
0, it will have the maximum space available for
data or
program storage. Anemptydata diskette is created by FORMAT. You may
copy
or write data or program files onto this kind of diskette in large, contiguous
blocks for fast accessing later.
42

VERSION 2.0 UPDATE
Changesto TRSDOS
NewLibrary Commands
These are described fully in the new pages for Section 2.
Library
Command
ANALYZE
DUAL
ECHO
HELP
HOST
MOVE
PRINT
~
RECEIVE
RESET
SCREEN
SPOOL
STATUS
T
Function
Gives diskette allocation information organized
by track
Duplicatesoutput to video and line printer
Beginsecho
of keyboard input to display
Helps with TRSDOS command syntax
Allows keyboard input from and video output to a
remote terminal via the serial interface
Copies multiplefiles and re-organizes adiskette
Prints any file in text format
Inputs Intel hex format data into RAM from the serial
interface
Resets TRSDOS (like pressing the RESET switch)
Copies Video Display screen contents to the printer
Saves printeroutputin adisk file for laterprinting; also
allows printing
of spool file while otheroperations are
mprogress
Displayscurrent top of usermemory and on/offstatus of
various TRSDOS functions
Advances printerto top
of form
43

MODEL II TRSDOS
New Utilities and Special Programs
These are described fully in the new pages for Section 3.
Name
LPII
MEMTEST
PRTBKSP
Function
Modifies the TRSDOS printerdriverfor use with the
Radio Shack Line Printer II (Catalog Number
26-1154)
Checks out random access memory
Modifies the TRSDOS printerdriverfor use with printers
capable of backspacing
Changesto 1.2Commandsand Utilities
The following have been changed:
AUTO
BACKUP
CLEAR
COPY
DEBUG
DlR
FORMAT
FORMS
FREE
I
KILL
SETCOM
TERMINAL
VERIFY
XFERSYS
For details, seethe replacement pages for Section 2.
OtherChanges
Keyaheads
TRSDOS allows keyaheads of up to 80 characters. This means you can type in the
next
command while previous ones are being executed.
Note: A keyahead will not be displayed until TRSDOS or the application program is
ready to interpret it.
For example ,type in these three lines, without waiting fOrTRSDOS READY after the
first
command:
DI R {SYS} (ENTER)
TIME (ENTER)
FREE (ENTER)
Press (BREAK) to interruptthe operation currently in progress; if akeyahead line is
available,
TRSDOS will begin interpreting it. Press (HOLD) to pause the operation
currently in
progress; press (HOLD) again to continue.
44

VERSION 2.0 UPDATE
WildCard
Certainlibrary commands allow you to specify acollection of files by using a
"wild-card" field inplace
of the file name and/orextension. An asterisk' '*" in a
file specificationrepresents awild-card field and means,
"any sequence of one or
more characters
here' ,.
Thewild-card option is available on the following commands:
KILL
MOVE
DIR (wild-cardfield for entire file name only)
Anew SVC has beenadded to allow Z-80 programs to use this wild-card capability.
Tofind afull description
of wild-card use, use the Index.
Alternate Directory
Forincreasedreliability of the diskette filing system, TRSDOS now sets up an
alternate directory.
If the main directory should become unreadable, the alternate
directory will be usedto allow continued access to the diskette. Details are given in
the descriptions
of FORMAT and BACKUP.
ABSolute Option
,,---' Many of theTRSDOS commands and utilities ask the operatorto confirm whether an
operation is to
be completed. TheABS option has been added to eliminate these
questions and thus simplify the use
of the command.
TheABS option is available on the following commands:
BACKUP
COPY
FORMAT
MOVE
45

MODEL II TRSDOS
DiskSwap Protection
The system now has the ability to detect when diskettes have been swapped
improperly, that is, while afile is open. TRSDOS will display an errormessage when
itdetects this
condition, and will cancel the read or write operation. See VERIFY.
NeworChangedSupervisorCalls (SVCs)
These are described in the new pages for Section4.
Name
VDCHAR
PRINIT
PRCHAR
LOOKUP
HLDKEY
OPEN
RENAME
WILD
RAMDIR
SORT
FILPTR
CLRXIT
VIDRAM
PRCTRL
AlBRCV
AlBTX
AlBCTRL
46
Function
Output a character to video
Initialize printer-driverparameters
Output a character to printer
(New) Lookup in atable
(New) Process the (HOLD) key
OpenlCreate a Program or Data File
(New) Rename afile
(New) Process awild-card specification
(New) Read the directory into aRAM buffer
(New) Sort items in RAM list
(New) Get informationabout acurrently
open file
(New) Execute CLEAR command and jump
to TRSDOS READY
(New) Transfer video to RAM or vice-versa
(New) Control printer operations
Receive character via Channel AlB
Transmit character via Channel AlB
(New) Control Channel AlB
Code
8
17
18
28
29
40
47
51
53
56
58
57
94
95
96/98
97/99
1001101

VERSION 2.0 UPDATE
Changesto Basic
New Keywords
These are described fully in the new pages for Chapter 3 of the BASIC Reference
Manual.
Keyword
ERRS$ Function
NAME Statement
Other Changes
PRINT Zones
Operation
Returns the lastTRSDOS errornumber and message
Renames adiskette file.
The PRINT zone width is
16 columns (was 14). Forexample:
PRINT "A", "B", "C", "0"
prints the letters in video columns 1, 17, 33 and 49.
NewError Codes
TRSDOS errorcodes 47-48 now indicate FC errors in BASIC.
TRSDOS errorcode 49 now indicates an
110 error in BASIC. (Use ERRS$ to get the
TRSDOS errornumber and message.)
LinePrinter
Themaximum LPRINT or LUST line is 255 characters (was 132).
Passwords
You can assign apasswordto aprogram when you SAVE it. This password will be
required for loading
or running the program.
Line Feeds
You can include line feeds in the program text, SAVE the program in ASCII format,
and LOAD the programlater(used to cause aDirect Statement error). Each line feed
in the file requires two bytes
of diskette storage.
Takecare notto create aline that will require more than 255 bytes for storage. This
maximum includes the line numberdigits and the space following the line number.
If the line contains embeddedline feeds, allow two bytes for each line feed.
47

MODEL II TRSDOS
OPEN Statement
To specify arecord length Of256, you can use either 256 ora. Forexample,
OPEN "0",1, "FILE", 256
and
OPEN "0", 1, "FILE". 0
are equivalent.
NEW
In addition to erasing the BASIC programin memory, this statementnow clears the
screen.
48

Section1
General Information

Model II TRSDOS
Introduction
Model II TRSDOS (' 'Triss-Doss'') is apowerful and easy-to-use Disk
Operating System, providing a
full set oflibrary commands and utility
programs. In addition, many ofthe most useful System routines can
be called
directly by user programs.
Library commands are typed in from the TRSDOS command level to
accomplish avariety of operations, including:
•Initialization
-setting Printer parameters, date and time, etc.
•
File-handling-copying, renaming, deleting, protecting, etc.
•File
access-loading into memory, listing to Printer or Display, etc.
•
Error identification
See the Commands section for details.
Utility programs provide essential services like:
•
Formatting blank diskettes.
•
Making backup copies of entire diskettes.
See the Utilities section for details.
System routines are executed via function codes instead ofcalls to absolute
memory addresses. Routines available
fall into seven categories:
•System control
•
Keyboard input
• Video Display input/output
•
Line Printer output
•File access
•
Computational functions
•Serial communications
See the Technical Information section for details.
50

.. ~
/
General Information
Notation
For clarity and brevity, we use 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:
DIR SYS
every letter and character should be typed exactly 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 filespec
indicates that you can supply any valid file specification (defined later) after
LIST.
. . . (ellipsis)
Indicates that preceding items can be repeated. For example:
ATTRIB filespec {option ,. .. }
indicates that several options may be repeated inside the braces.
Ii'
This special symbol is used occasionally to indicate ablank-space character
(ASCII code32 decimal, 20 hexadecimal).
RENAME~ FILE/A JDTO Yf FILE/B
x'nnnn'
Indicates thatnnnn is ahexadecimal number. All othernumbers in the text of
this book are in decimal form, unless otherwise noted. For example:
X7000'
indicates the hexadecimal value 7000 (decimal 28672).
51

Model II TRSDOS
Memory Requirements
TRSDOS occupies 6.1 tracks on the System diskette (39 ,040 bytes). However,
only asmall portion is actually in memory at anyone time. The Supervisor
Program, input/output drivers, and other essentials are always in memory.
Auxiliary code is loaded as needed into an "overlay area".
Memory addresses 0through 10239 (XO'-X'27FF) are reserved for the Oper-
ating System. Certain commands, called "high overlays", also use memory
addresses up
to X'2FFF' (details provided in the Commands section). User
programs must be located above X'27FF'; and you may want to locate them
above X'2FFF' to allow use of the high overlays without loss of your program.
DECIMAL
ADDRESS
a
10240
12288
TOP*
32767 or
65535
SYSTEM AREA
USER AREA (SHARED WITH
TRSDOS "HIGH OVERLAY COMMANDS")
USER AREA UNTOUCHED**
BYTRSDOS
MAYBE
RESERVED BY TRSDOS FOR
SPECIAL PROGRAMMING
Last Memory Address
MEMORY REQUIREMENTS OF TRSDOS
HEX
ADDRESS
X'OOOO'
X'2800'
X'3000'
TOP*
X'7FFF'or
X'FFFF'
Note: The term "user program" applies to any program which is not apart of
TRSDOS. Therefore BASIC is auser program. For memory requirements of
BASIC, see the BASIC Reference Manual.
"'TOP is amemory protect address set by TRSDOS. IfTRSDOS is not protecting
high memory,
then TOP is the same as "Last Memory Address".
**Single-drive COpy from one diskette to another, BACKUP and FORMAT use
all user memory.
52

General Information
Loading TRSDOS
See the Operation Manual for instructions on connection, power-up and
inserting the System diskette.
Note: ASystem diskette must be in Drive 0(the built-in unit) whenever the
Computer is in use. Whenever the Computer is turned on or reset, it will
automatically loadTRSDOS from Drive
O.
After the System starts up, it will prompt you to enter the date. Type in the
date in MMjDDjYYYY form and press 13m*I . For example:
07/04/1979
for July 4, 1979.
Next
the Systemwill prompt you to enter the time. To skip this question, press
.
The time will start at 00:00:00.
To set the time, type in the time in
HH.MM.SS 24-hour form. Periods are
used instead
of colons since they're
easier to type in. The seconds
are op-
tional. For example:
14.30
for 2:30 pm.
The System will record
the time and
date internally and return with the
message:
TRSDOS READY
53