CGC_7900_Preliminary_DOS_Manual_Jul1981 CGC 7900 Preliminary DOS Manual Jul1981

CGC_7900_Preliminary_DOS_Manual_Jul1981 CGC_7900_Preliminary_DOS_Manual_Jul1981

User Manual: CGC_7900_Preliminary_DOS_Manual_Jul1981

Open the PDF directly: View PDF .
Page Count: 212

Download
Open PDF In Browser	View PDF

CHROMATICS
'.

CGC 7900 COLOR GRAPHICS COMPUTER SYSTEM
PRELIMINARY DOS MANUAL
(with Assembler and Text Editor)
July, 1981

Copyright (C) 1981 by Chromatics, Inc.
2558 Mountain Industrial Boulevard
Tucker, Georgia 30084
Phone (404) 493-7000
TWX 810-766-8099

This document is an advance release, provided for
informational purposes
only.
The
specifications
contained herein are subject to. revsion prior to
shipment of the product.

PUBLICATION COMMENT FORM
~ase use this
sheet to give us feedback on the enclosed
:umentation. Your comments on errors or omissions, suggested
anges, format of presentation, etc., will be helpful .in
eparing future manuals. Wherever possible, refer to specific
ge numbers in your comments below.
After completing this
rm, mail to:

Chromatics, Inc.
2558 Mountain Industrial Boulevard
Tucker, GA 30084
Attn:

R&D Department

Name:

Date: ____________

Company Name:
Name/Model Number of Product: ___________________________
Title of Publication:
Preliminary?_____

Date of Publication Release:
Page No.

Comments

CONVENTIONS USED IN THIS DOCUMENT
1. Any keys which have labeled caps will be called by their
full names, capitalized and underlined.
For example,
the
carriage return key will be denoted by
RETURN
2. The modifier keys, ~, SHIFT, Mi, and HZ, must be held
down while striking the key they are to modify. Note that these
four keys do not generate any characters on their own, but
simply modify the character which is struck simultaneously.
This process of holding down a modifier key while striking
another key will be denoted by the modifier AND the key being
underlined together. For example,
CTRL F

would indicate that the ~ key should be held down while
striking the· F key.
If two or more modifiers are needed
simultaneously, they will all be underlined together:
CTRL SHIFT T
mean that BOTH modifiers, SHIFT
30wn while striking the T key.

~ould

and~,

should

be

held

Variable parameters will be enclosed in angle brackets, < >.
items enclosed in th~se brackets will be explained in full
In the text which immediately follows.

5.

~y

Optional parameters will be enclosed in square brackets [ ].
items which may be repeated will be followed by an ellipsis
:three dots).

l.

~y

:xample of (3) and (4):
, [,, ••• ]
'he parameter  is required. The parameters , , and
:0 on, are optional.
Any number of these may be included.
All
,hree types of parametOers would be explained immediately beneath
,he example which contained them •
•

Zeros will be slashed (8), alphabetic 0 will not be slashed.

TABLE OF CONTENTS
SECTION 1 - THE DISK OPERATING SYSTEM
INTRODUCTION
DISKETTES
ENTRY INTO DOS
DOS COMMAND LINE
DISK FILE NAMES
DISK DRIVE NUMBERS
SECONDARY FILE NAMES
FILE NAME PATTERNS
TRANSIENTS
DIR
COPY
FORMAT
INITIALIZING A NEW DISKETTE
RENAME
KILL
COMPRESS
DELETE
BUFF
DRAW
APPEND
PICTURE
REFRESH
IMPLODE
EXPLODE
STORE
FETCH
DEBUG
VERSION
SUMS

XREF
DOS ERROR MESSAGES
SECTION 2 - THE EDITOR

1- 1

1- 3

1- 4

1- 7

1- 9

1- 19

1- 13
1- 14
1- 15
1- 17

1111-

18
23
27
29

1- 39
1- 33
1- 35
1- 37
1- 39

1- 49
1- 41
1- 42
1- 44
1- 45
1- 46
1- 47
1- 49
1- 59
1- 51
1- 52
1- 53
1- 55

2- 1

INTRODUCTION TO THE EDITOR
INLINE

2- 3
2- 5

EDITOR COMMANDS
OPEN
GET
LIST
PRINT
INSERT
MODIFY
DELETE
FIND
SUBSTITUTE
LAST

2- 7

2- 8
2- 9
2- 19

2222-

11
12
14
16

2- 17

2- 18
2- 29

PUT
CLOSE
PAGE
DRIVB
EXI'!'

,

ABOR~

SECTION 3 - THE ASSEMBLER

.

222222-

21
22
23
24
25
26

3- 1

INTRODUCTION TO THE ASSEMBLER
ASSEMBLER COMMAND LINE

3- 3
3- 4

SOURCE FIL.E FORMAT
LABELS
INSTRUCTIONS
OPERANDS
COMMENTS

33333-

7
8
9
18
11

INSTRUCTION EXAMPLES
ARITHMETIC'
COMPARE
LOGICAL
SHIFT AND ROTATE
BIT OPERATIONS
EFFECTIVE ADDRESS
MOVE DATA
MOVE MULTIPLE
BRANCH, JUMP
DECREMENT AND BRANCH
SET
SYSTEM CONTROL

3333333333333-

13
14
15
16
16
17
17
18
19
28
22
23
24

INSTRUCTION TYPES

3- 25

EXPRESSIONS

3- 27

PSEUDO-INSTRUCTIONS
ORG (ORIGIN)
EQO (EQUATE)
SET
DC (DEFINE CONSTANT)
DS (DEFINE STORAGE)

3- 29
3- 38
3- 31
3- 32
3- 33
3-35
3- 36
3- 37
3- 37
3- 38
3- 38

END

PAGE
LLEN
NOLST
LIST
ADDRESSING MODES
REGISTER DIRECT
ADDRESS REGISTER INDIRECT
ADDRESS REGISTER INDIRECT/POST INCREMENT

3333-

39
39
4-8
48

ADDRESS REGISTER INDIRECT/PREDECREMENT
ADDRESS REGISTER INDIRECT/DISPLACEMENT
ADDRESS REGISTER INDIRECT WITH INDEX
ABSOLUTE SHORT
ABSOLUTE LONG
PC WITH DISPLACEMENT
PC WITH INDEX
IMMEDIATE
ASSEMBLY ERRORS
APPENDIX A - PROGRAMMING THE CGC 7999

33333333-

41
41
42
43
43
44
45
46

3- 47
A- 1

MODULES
THE LINKING PROCESS
MODULE CONSTRUCTION
BOOT MODULES
INPUT/OUTPUT MODULES
ARGUMENT PARSING
MODE MODULES
PLOT MODULES
ESCAPE AND USER MODULES
REGISTER SETUP FOR MODULES

AAAAAAAAAA-

4
6
7
8
9

WINDOW TABLE
WINDOW STATUS AND ESCAPE CODE STATUS

A- 21
A- 24

JUMP TABLES
PLOTTING FUNCTIONS
DOS JUMP TABLES
INLINE CALLING SEQUENCE

AAAA-

CMOS MEMORY ALLOCATION
LOW RAM ALLOCATION
THE USER FILE TABLE

A- 43
A- 45
A- 47

WRITING TRANSIENTS

A- 49

CUSTOM CHARACTER SETS

A- 57

INSTALLING A NEW CURSOR

A- 61

DOS ERROR MESSAGES

A- 65

II

12
15
18
29

25
32
37
42

CGC 79l:HJ

Preliminary DOS Manual

,-

SECTION 1 - THE DISK OPERATING SYSTEM

Page 1-1

CGC 7999

Preliminary DOS Manual

Page 1-2

Preliminary DOS Manual

:GC 7900

Page 1-3

INTRODUCTION
rhis is the manual for the Chromatics CGC 7900 Disk Operating
;ystem (DOS), an optional feature of the 7900 series of color
~raphic
computers.
The Disk
Operating
System
uses
two
jouble-density flexible disk drives for program
and
datastorage. A fixed disk drive with 10 megabytes of storage is
also available. The DOS option consists of these parts:
Disk drives
PROMs (firmware)
A diskette with system programs
This manual
The disk drives and PROMs are factory-installed, and should
require no attention by you· (except that the fixed disk may
require special unpacking; instructions for this· ·are attached to
your unit if applicable).
The diskette contains programs which provide an
interface
between the disk drives and your programs or data. Routines are
provided to save data onto a disk, to retrieve data from a disk,
and to manipulate the contents of the disks.
This diskette
should be handled carefully as you are learning to use the DOS.
You should make a copy of this diskette at your earliest
opportunity. Instructions for copying a diskette are included
in this manual (see the FORMAT. and COpy commands).
This manual begins by describing the commands and utility
routines available in DOS. In later sections, the Text Editor
and MC68000 Resident Assembler are discussed.
These
two
programs allow you to create text files and assembly language
programs on the disk, and to generate executable binary machine
code for the 68000 processor.
Detailed descriptions of the CGC 7900 special features, such as
the color graphics plotting capability, are not provided here.
Please refer to your User's Manual for information on other
aspects of the CGC 7900.

CGC 7908

Preliminary DOS Manual

Page 1-4

DISKETTES
DOS stores information on the surface of disks, which are coated
with a magnetic material.
Flexible diskettes, or
-floppy
disks,- area very reliable and convenient way to store data.
A
flexible disk will perform well for many hours of use, if a few
simple precautions are observed:
HANDLING - DO NOT touch the exposed surface
which is visible through a slot on either side
DO NOT attempt to remove the circular diskette
dark envelope. Handle the diskette carefully,
it.

of the diskette,
of the diskette.
from its square,
and do not fold

LABELING - A diskette is provided with adhesive labels which
should be used to note the contents of the diskette.
Write on
these labels BEFORE attaching the label to the diskette. If you
must write on a label after it has been attached to the
diskette, use a felt-tip pen and press gently. A ball-point pen
will crease the disk and may cause permanent damage.
INSERTING - To insert a diskette into a drive, first remove the
diskette from its paper sleeve. Hold the diskette gently, with
the label UP, and the arrow on the label aiming toward the
drive. Open the drive door by pressing the rectangular button
until the door snaps open. GENTLY slide the diskette into the
drive until it is completely inside the door (it may seat with a
soft -click-). Press the door shut.
To remove the diskette,
press the rectangular button again.
STORAGE - When a diskette is not in use, it should be removed
from the drive and stored in its paper sleeve.
Store the
diskette away from dust, away from extremely high or low
temperatures, away from moisture, and AWAY FROM MAGNETIC FIELDS.
Protect the diskette from magnets, motors, transformers, or
anything else which could create magnetism.
OPERATION - When a disk drive is in use, the red light in the
drive door will illuminate.
It is extremely important that
nothing interfere with the disk while this light is on. While a
disk is in use, removing the disk, pressing BESET on the
keyboard, or turning the power off, may damage the "data on a
disk.

:GC 7900

Preliminary DOS Manual

Page 1-5

rhe fixed disk is a sealed unit, located in the base of the 7900
=hassis. It is not subject to many of the restrictions above,
since it is hidden away from normal view. But the warning about
interrupting a disk operation in progress is still valid: if you
bave any reason to believe the system is accessing your fixed
disk, DO NOT press RESET or otherwise interrupt the process.
If
you give the system a command to access the fixed disk, be sure
the command has been completed before turning the system off or
pressing RESET.
WRITE-PROTECTION - A flexible diskette may be protected from
accidental destruction by uncovering its write-protect notch.
Some diskettes are shipped with the notch covered, and some have
it uncovered when you receive them. In either case, the notch
must be covered or DOS will not be able to write on the disk.
The write-protect notch is a small (1/4-) hole on the front edge
of the disk.

CGC 79""

Preliminary DOS Manual

Page 1-6

Preliminary DOS Manual

CGC 7900

Page 1-7

ENTRY INTO DOS
The Disk Operating System is entered by pressing the labeled key,

The DOS log-on message should immediately appear on the screen.
If this does not happen, it can be because the state of the
system is not what DOS expects to find (for example, if the
screen is not connected as the proper output device).
You can
optionally enter the Disk Operating System by striking three
keys,
RESET

CTRL BOOT

This sequence initializes
cause entry into DOS.

~

the

entire

system

and

will

always

The DOS log-on message should now appear:
CGC Disk Operating System --- Version 1.4
Copyright (c) 1981 by CHROMATICS, INC.
ENTER USER PASSWORD =
DOS will print its version number. This number should be
in any communications to Chromatics concerning the DOS.

noted

The DOS log-on message will request your User Password. At this
point, you may enter a 2-character password and press the RETURN
key, or you may simply press RETURN.
If you do not enter a
password, you will only have access to Public files which are
not assigned a password. If you do enter a password, you will
have access to all Public files, as well as any files whose
password matches yours.
Legal characters for a User Password are: digits 8-9, upper and
lower case alphabetic characters, and these special characters:

[ \ 1

~

_ ' { I } -

Entering any other characters may cause the
your password and assign you to Public files.

system

to

ignore

CGC 790.

Preliminary DOS Manual

Page 1-8

NOTE: The User Password system in DOS is not· designed
to offer a high level of protection. Its main purpose
is to help organize files into groups, so that a user
will see only the files he must work with.
This is
especially important in the case of the hard disk,
where several hundred files may exist in the directory.
After completing the log-on procedure,
asterisk (*) as its prompt character. The
DOS is ready to accept a command.

DOS prints a green
asterisk means that

Preliminary DOS Manual

CGC 7909

Page 1-9

DOS COMMAND LINE
When you are entering commands to DOS, all of the text editing
functions labeled on the cursor keypad may be used to edit your
input line. The left and right arrow keys move the cursor.
around on the input line. the ~ key moves the cursor to the
beginning of the input line. The functions labeled in blue are
accessed by holding the ~ modifier and pressing the indicated
key: these functions are Insert Character, Delete Character,
Clear Line, and Clear EOL. Pressing RECA~L brings back a copy
of previous lines. RECALL and SHIFT RECALL may be used to
retrieve any line from the "Recall Buffer." Once recalled, a
previously entered line may be edited with the other functions.
Regardless of where the cursor is on the input line, ALL
characters visible on the input line are accepted when the
RETURN key is pressed. DOS does nothing with your commands until
you press RETURN.
If you press PELETE instead of RETURN, DOS
ignores the line you typed.
(All of these functions are a part of the Inline Editor, used
for DOS, the Monitor, and other 7900 programs.
The Inline
Editor is discussed in more detail in the 7900 User's Manual, and
in Section Two of this manual.)

DOS commands are described in detail in this
simple words or abbreviations, such as
DIR

manual.

Most

are

files

on

(followed by RETURN)

which lists the directory of a disk (the names of
that disk).

the

You may enter several DOS commands on the same line, separating
them by a colon (:). For example, the following command would
list the disk directories from drives I and 2:
DIR/l:DIR/2
(No space should be typed on either side of the colon.)· You may
type as many commands as will fit on a single line of the
screen. If any command causes an error, DOS will not process
the rest of the commands on that line.

CGC 7999

Preliminary DOS Manual

Page 1-19

DISK FILE NAMES
DOS is a file oriented system. When you type a command . to DOS,
you are actually entering the name of a disk file.
DOS looks
for the' file, and if the file is found (and is executable), it
is loaded into memory and executed.
A file name may have several parts:
The primary name, which may be one to eight
characters, and may contain the special characters
[

\

]

",

alphanumeric

, { I ,} -

The secondary name, which
is
always
three
alphanumeric
characters. The secondary' name is separated from the primary
name by a period (decimal point).
The secondary name is
optional. If it is omitted, DOS will usually append a secondary
name to the file name (depending on what the file name is to be
used for).
A password, which must match the password assigned to the file.
The password is separated from the name by a dollar Sign ($) •
If a password is entered, it must precede the drive number.
The
password is optional. If it is omitted, it is assumed to be the
password under which you logged onto DOS.
A drive number, identifying the disk drive on which the file
resides. The drive number is separated from the name by a slash
(f). The drive number is optional. If it is omitted, it will
be assumed this file resides on the same drive which responded
to the last DOS command (the drive from which the last command
was loaded).
The four parts of a file name (primary name, secondary name,
password, drive number) must occur in the order listed.
If any
of the optional parts are omitted, the remaining parts must
occur in the required order.

CGC

Preliminary DOS Manual

79~"

Page 1-11

Examples of legal file names:
FILEname
STORY.SRC
PROGRAM/2

USRT29NE$PW
LISTING.OBJ/l
HardLuck.BUF$ED/3

Examples of improper file names:
THISISTOOLONG

Too many characters in primary name only the first eight characters would
be recognized, so this is equivalent
to THISISTO. It would, however, still
be accepted.

oops/A

Illegal drive number.

NOWAYl.SYS

Illegal character in primary name.

BADone.GO

Secondary name too short.

Wrong/l.SRC

Incorrect order.

CGC 7998

•

Preliminary DOS Manual

Page 1-12

Preliminary DOS Manual

CGC 7900

Page 1-13

DISK DRIVE NUMBERS
The CGC 7900 supports up to three disk drives: two flexible disks
and a hard disk. Many disk commands require specifying the drive
number of the disk to which the command refers.
The followin~
numbers apply:
Drive 1:

the left-hand flexible disk

Drive 2:

the right-hand flexible disk

Drive 3:

the hard disk

You may always specify the drive number if you wish.
Anytime
you do not specify a drive number, DOS assumes you are still
using the same drive you used in a previous command.
'--

If a drive number of B (zero) is entered, it implies that DOS
should search all drives to locate the requested file.
The
search begins with drive 1. (If a new file is being created,
the drive number must be implicitly or explicitly specified, so
a drive number of zero is not allowed.)
When you enter DOS, immediately after pressing the DOS key, the
system does not know which drive you want to use.
The FIRST
command you enter to DOS acts as if you had specified a drive
number of zero, so DOS will search all drives in your system in
an attempt to execute the command. If this search succeeds, DOS
now knows which drive you want to use, and it will stay with
that drive until you specify a different drive number.
On the other hand, if your first command to DOS fails (as it
would if you misspelled a command), DOS will display an error
message. DOS will now default back to drive 1.
The next
command you enter will assume that drive 1 is
in
use.
Therefore, if an error occurs in your FIRST command to DOS, let
your SECOND command specify a drive number unless you want to
use drive 1.
The feature of -remembering- the current drive applies' only to
commands. DOS only remembers where the last COMMAND carne from,
not the last filename. If you type:
KILL/2 filename/3
The KILL command is coming from drive 2, so DOS remembers drive
2 and will search it for the next command (unless you specify a
different drive number).

CGC 7900

Preliminary DOS Manual

Page 1-14

SECONDARY FILE NAMES
The following secondary file names are recognized by DOS:
.SYS

"System" file. These are executable by DOS, simply
by typing the file name as a DOS command. .SYS files
are not listed by the OIR command unless specifically
requested. .SYS files are called "transients" since
they are part of the set of DOS commands, but do not
reside in memory at all times. .SYS files are listed
in the directory in YELLOW •

• KIL

"Killed" file.
These are files which have been
removed from active status by the KILL command. A
.KIL file will be removed by COMPRESS, however it may
be recovered before COMPRESS by using RENAME.
.KIL
files are not listed by the OIR command unless
specifically requested. .KIL files are listed in the
directory in RED.'
All of the file types below are
listed in GREEN in the directory •

• SRC

"Source" file. These files contain ASCII text,
as the source code of an assembly program.

.BUF

"Create"Buffer" files. These files are created by
the BUFF command and recalled with DRAW.
They
contain commands used to draw pictures •

• PIC

"Picture" files. These files contain a dump of up to
two megabytes of image memory. They are created with
PICTURE and recalled with REFRESH •

• RLE

"Run-Length Encoded" files.
These files contain a
compacted version of the data from image memory.
They are created with IMPLODE and recalled with
EXPLODE •

• ABS

"Absolute" binary files.
These files contain a dump
of bytes from selected areas of memory.
They are
created with STORE and recalled with FETCH.-

such

CGC 79'H'

Preliminary DOS Manual

Page 1-15

FILE NAME PATTERNS
DOS allows a "pattern- to be u.sed in place of a file name under
many conditions. A pattern permits a single command to affect
several files at once, or permits a command to affect any file
meeting a set of criteria. Depending on the command, using a
pattern will either affect the FIRST file on a disk which
matches the pattern, or ALL files which match.
Details are
given in the descriptions of the individual commands.
A pattern may consist of any combination of these items:
A primary name
A secondary name

(example: .SYS)

A wild card -.- in either the primary or secondary name
A password
A drive number
If the primary
The asterisk -.- performs a special function.
name is an asterisk, it will match any file name.
If the
secondary name is an asterisk, it will match any secondary name.
If either field CONTAINS an asterisk (in addition to other
characters), the asterisk will match any single character in a
file name. If the asterisk is in the last position of a field
(in addition to other characters), it will match any set of zero
or more characters.
If the primary name is blank, an asterisk is assumed to be
inserted in place of the blank. This means that the following
two patterns are equivalent:
*.SRC
.SRC
Either of these patterns would match
name is .SRC (a text file).

any

file

whose

secondary

If the secondary name is blank, it will match any file EXCEPT a
.SYS or a .KIL file. These files are never matched except when
specifically asked for, by using a .SYS, .KIL, or .* pattern.

Preliminary DOS Manual

CGC 7998

Page 1:-16

Some examples of patterns:
A*

Matches any file beginning with -Aexcept .SYS and .KIL files

A*.*

Same as -A*-, but includes .SYS and .KIL

*.BUF

Matches any .BUF file

*.*

Matches ANY file

Patterns can be very convenient, but they should be used with
caution. Suppose a program created a set of scratch files, and
named them Xl, X2, and so on. They could all be removed at once
with the command
KILL X*
but this would also KILL any other files whose names
the letter X.

began

with

Preliminary DOS Manual

CGC 7999

Page 1-17

TRANSIENTS
Transients, or transient programs, are the files which make up
the set of commands DOS recognizes. By typing the name of a
command, you tell DOS to search the disk for the file with tha
same name. If the file is found, it is loaded and executed,
causing your command to be carried out.
This system of swapping commands in and out of memory as needed
gives DOS great flexibility. The entire DOS need never reside
in memory at once; only the current command is occupying space
in memory. Further, it is simple for you (or Chromatics) to add
commands to the set of commands DOS recognizes, by writing
assembly language programs to carry out the command.
Transients
are stored on the disk with a secondary name of .SYS, and are
not visible in the disk directory unless you specifically ask to
see them.
This section discusses the transients, or commands, supplied
with DOS. When typing in a command to DOS, the various parts of
the command line must be separated by delimiters.
Valid
delimiters are:
SPACE
comma (,)
Certain control-characters and punctuation marks will
as delimiters, but their use is not recommended since
make the command line difficult to read.

also act
it would

If a command line contains several file names, delimiters must
occur between the names. Only a SINGLE delimiter should be used
to separate each pair of items on the command line; i.e., you
should NOT type a comma followed by a space. This would usually
cause a RSyntax Error R message.

Preliminary DOS Manual

CGC 7991

Page 1-18

DIR
Format:
DIR

[]

[,]

RETURN

Where:
 is a file name, or a pattern
which may contain wild cards.
 are described below.
The DIR (Directory) command lists the files in the directory of
a disk. Several options can be specified to tell the DIR
command which files you are interested in.
Typing DIR by itself will give you a list of most files on the
disk whose password matches yours. Files with either a .SYS or
a .KIL secondary name are not listed when you type DIR.
If  is included, only files matching the pattern are
listed. Some examples of using a pattern with DIR are shown on
the following pages.
If you want to examine the files of another user, you may enter
that user's password as part of the pattern.
It should be
separated from the rest of the pattern by a dollar sign ($).

~

You may use the DIR transient, residing on one disk, to examine
the files of another disk. This is normally done only if the
second disk does not contain the DIR transient.
It
is
accomplished by specifying the drive number of the .disk whose
directory is to be listed. This number is preceded by a slash
(I).

Preliminary DOS Manual

CGC 790S

Page 1-19

In the examples below, and on the following pages, the RETURN key
has been omitted, and a space bas been used as a delimiter, so
that the example will closely resemble what you will see on the
7900 screen.
DIR

List all except .SYS and .KIL files

DIR .*

List ALL files (including .SYS and .KIL)

DIR .SYS

List all .SYS files

DIR *.SYS

List all .SYS files (same as above)

DIR BR*

List all files whose names begin with
the letters BR. Possible matches would
be BR, BREAK, BROWN, etc.

DIR T*N

List all files whose names are three
characters long, begin with T, and end
with N (TEN, TON, etc.)

DIR $XY

List

DIR .*$XY

List all files under password ·XY·

DIR/2

List files on drive 2

DIR/l /2

List files on drive 2, using the DIR
transient living in drive 1

DIR/l .KIL/2

List all killed files on drive 2, using
the DIR transient from drive 1

fi~es

under password ·XY·

Preliminary DOS Manual

CGC 7900

page

~-~~

You can also append some options to the DIR command, using a
semicolon (;) to separate them from the pattern. These options
are:
P

List Public Files only, not the files under your
password (if you logged in with no password, this
is equivalent to listing the normal directory).

L

Give Long version of the directory, including the disk
name, address of next available space on the disk,
address and length of each filel and -attributeflags pertaining to each file.

S

Give Short version of the directory, with file names
only. Note: LONG version is default.

A

List files stored under ALL passwords.

Examples:
DIR ;P

List public files

DIR .*;P

List all public files

DIR .*;L

List all files, with details

DIR/3 .*;LP

List all public files on drive 3, with
details

DIR ; A L i s t files under all passwords (except
.SYS and .KIL files)
DIR .*;A

List files under all passwords, including
.SYS and .KIL files

NOTE: A SPACE must be present after the command DIR.
No space is used between a pattern (if any) and the
semicolon. This is illustrated in the examples above.

Preliminary DOS Manual

CGC 7909

Page 1-21

The disk directory is displayed in this form:
Free Address: $nnnn

DISKNAME

Free Length: $xxxxx

------------------------------------------------------ ---~-------

Filename
Prefix
Sfx

Status
••••••••

File
. File
Address Length

Samp1e12.SRC

w.......

$4999

File Origin
Date
Time

Last Accesa
Date
Time

$298

The disk is named ·DISKNAME.- The first free byte on the disk is
byte number $nnnn, and the length of the free space located at
that byte is $xxxxx bytes. (All numbers prefixed by the dollar
sign are in hexadecimal, base 16.)
One file is listed in this directory. It is named Samp1e12, and
has .SRC as a secondary name. The file begins at byte $4999 and
occupies $299 bytes of the disk.
It is write-protected (see
below).
The ·Status· column of a directory may show any of the
characters:

following

w

The file is write-protected.

d

The file is delete-protected and cannot be
destroyed by COMPRESS.

e

The file is execute-only.

o

The file is odd length. A file will only occupy
exactly the number of bytes it requires, unless
it contains an odd number of bytes. In this case,
a single extra byte of storage is used by DOS to
cause the file to occupy an even number of bytes.
Note the efficiency of this scheme, in comparison
with other disk operating systems which use blocks
of 128 or 256 bytes, regardless of the actual file
length.

k

The file has been KILLed.

CGC

79~'"

Preliminary DOS Manual

Page 1-22

If your system contains the optional Real-Time Clock, DOS will
also display time and date information in the directory.
The
last columns of the directory will show when a file was created,
and when it was last accessed.
The ·Free Length- entry in the directory always shows the length
of the largest free space available on the disk. If this number
approaches zero, the disk is getting full and should
be
COMPRESSed. See the COMPRESS command for details.

Preliminary DOS Manual

CGC 7999

Page 1-23

COpy
Format:
COpy





RETURN

Where:
 and  are each file names, or file name
patterns. Wild cards are allowed.

COpy produces a copy of a file, on the original disk or on
another disk. The name of the copy may be the same as the
original, or different. It is NOT legal to copy a file to the
same disk and retain the same name, however.
If a pattern is used instead of a file name, all files matching
the pattern are copied. This provides an easy way to transfer
only .SYS files to a new disk, for example.
NOTE: If  is located on the same
, a wild card is not allowed in the
name.

drive as
secondary

NOTE: If the secondary names and the drive numbers of
 and  are identical, only ONE file is
copied regardless of any wild cards in the file names.
This rule, and the one above, are required to prevent
DOS from copying a copy (of a copy of a copy ••• )
.KIL and .SYS files are not recognized
specifically requested (see examples).

by

COpy

unless

The new file produced by COpy will have the same password as the
'old file, unless the command line specifically changes the
password (by providing a password on the destination name).
The new file produced by COpy will always have the same status as
the old file (execute-only, delete-protected, etc.). See DIR for
a discussion of status attributes.

CGC 7998

Preliminary DOS

Manua~

Page 1-24

Examples:
COpy AX BX

Make a copy of AX, call it BX, and
put it on the same disk with AX.

COpy AX/l /2

Copy AX from drive I to drive 2.

COpy AX/l BX/2

Copy AX from drive 1 to drive 2, and
call the copy BX.

COpy T*/l /2

Co~y all files beginning with the
letter T, from drive 1 to drive 2
(except .SYS and .KIL files)

COpy *.SYS/l /2

Copy all .SYS files from drive 1 to
drive 2

COpy AZ BZ$aa

Make a copy of AZ, call it BZ, and
give it password waa w•

COpy AZ$aa $bb

Copy file AZ from password waa w to
password wbb w•

COpy .SRC .BUF

Copy all text files into .BUF files.

The destination disk should always be formatted before you try
to COpy anything onto it. Formatting prepares a disk to receive
data. (The FORMAT command is discussed after we complete the
description of COpy.)

Preliminary DOS Manual

C 7909

Page 1-25

only the drive numbers are specified, and no file name
ttern is given, a special full-disk
COpy occurs.
This
pies all data from the source disk to the destination disk,
lcluding the disk name and the entire directory. This kind of
IPY is normally used to produce a backup copy of an entire disk._
FULL-DISK COPY DESTROYS ALL DATA ON THE DESTINATION DISK.
cample:
COpy /1 /2

Copy the entire disk in drive 1
onto the disk in drive 2.

NOTE: A SPACE must occur between the COpy command and
the source drive number. If drive 1 contains the COpy
transient, the command above is equivalent to
COPY/1 /1 /2
In this case, the drive ~umber of the disk
the COpy transient is - specified. . The
command would NOT be legal:

containing
following

COPY/l /2
This command specifies the transient drive and the
source drive, but does not specify the destination
drive. The result is an -Argument Error- message.

r~e~~m~nary

UU5

Manual

Page 1-26

When a diskette (floppy disk) is FORMATted, it is defined to be
either single-density or double-density.
A single-density
diskette can hold up to 256,256 bytes and a double-density
diskette can hold up to 599,184 bytes. The 7909 normally uses
only double-density diskettes.
If you attempt a full-disk COpy between two disks
different densities, a warning will be displayed:
Density mismatch.

which

have

Continue (YIN) ?

Press the ·Y· key if you want to proceed. If you asked DOS to
copy from a single-density diskette
to
a
double-density
diskette, the -density mismatch· will not be a problem, since
all the data on a single-density diskette can easily fit onto a
double-density diskette. If, however, you asked DOS to copy
from a double-density diskette onto a single-density diskette,
you will get an error after the disk has been halfway copied.
A similar situation arises '--if you attempt a full-disk COpy
The capacity of a
between a diskette and the hard disk.
diskette is approximately 256K bytes Or 5l2K bytes, depending on
the density. The hard disk capacity is 10M bytes. You will see
this warning:
Capacity mismatch.

Continue (yIN) ?

If you press the ·Y· key, copying will proceed. BEWARE: If you
asked DOS to copy from a diskette to the hard disk, EVERYTHING
on the diskette will be copied and no errors will be displayed.
However, the hard disk directory will now be a copy of the
diskette directory, and will reflect a disk size of 5l2K bytes
instead of 19 Mbytes. This will render 95' of the hard disk
inaccessable until the hard disk is reformatted.
If you asked DOS to copy from the hard disk to a diskette, an
error will occur as DOS attempts to write past the end of the
diskette.

Preliminary DOS Manual

CGC 79""

Page 1-27

FORMAT
Format:

I

FORMAT

[]

[;]

RETURN



is the name given to the disk being formatted.
If omitted, the revision level of DOS is used
to form the'disk name.



is the number of the disk drive containing the
disk to be formatted.  is required.



are options, desribed below.

Where:

FORMAT initializes a disk, preparing it for data.
A new disk
must be formatted before it can be used. Formatting destroys all
data on a disk.
After a disk has been formatted, it contains a
blank directory, and no files.
The blank. directory shows only
the disk's name, its size, and allows POS to determine the disk's
density (single or double).
If  is specified, the disk is given this name.  may
be one to eight alphanumeric characters.
If  is not
specified, the disk is named ·DOSRevXX· where XX is the version
of DOS which initialized the disk. A disk formatted by DOS 1.4
would be named ·DOSRev14·.
FORMAT prints the message:
Format drive n.

Continue (yIN) ?

where n is the drive number FORMAT will initialize.
You are
given this chance to abort the process. Press the ·Y· key to
continue, or any other key to abort.
You may also insert a
different diskette in the drive before pressing ·Y·.

Preliminary DOS Manual

CGC 799"

Page 1-28

When DOS begins formatting the disk, it prints
Formatting drive n.
If successful, control returns to DOS with no further messages.
If an error occurs, such as a bad block detected on . the
diskette, ~rror messages are printed and the FORMAT should be
tried again.
If errors continue, the diskette should
be
discarded.

Options may be included in the  field, separated from the
rest of the FORMAT command by a semicolon. Allowed options are:
;D

double density

;S

single density

;y.

·Yes,· proceed with formatting

The default format for diskettes is double density. If desired,
a single density diskette may be formatted using the ·S· option.
A diskette created for Single density may be used on any CGC
799" system, and may possibly be useful in exchanging data with
other computer systems using single density diskettes.
However,
the directory of any 7999 disk will be different from that used
by other disk operating systems, so it will not generally be
possible to insert a CGC 799" disk into any other computer
system. Nor is it generally possible for the 79"9 to read a
diskette created by another computer system.
Option ·Y· prevents the system from asking the ·Continue?·
question above. If option ·Y· is used, the disk or diskette
will be immediately formatted with no questions asked.
Option
·Y· should be used with caution.

CGC 7gee

Preliminary DOS Manual

Page 1-29

INITIALIZING A NEW DISKETTE
Formatting prepares a disk for data, but does not store anything
on it. A freshly formatted disk has a blank directory. Here is
a sample procedure which might be used to format a brand new
diskette:
Load a disk containing the FORMAT command, and other
into drive·l. Load a blank disk into drive 2.

transients,

Enter the following:
FORMAT/l NewDisk/2
and press RETURN.

The FORMAT transient responds:

Format drive 2.

Continue (Y/N) ?

Press the wyw key. The formatting proceeds. When complete, and
no error messages have been printed, you can assume the new disk
is now formatted properly. It has the name wNewDisk w•
Now you
may wish to copy the DOS transients onto this disk, so that it
will be useable without referring to other disks. Enter:
COPY/l *.SYS/l /2
and press RETURN. All system transients
copied to the new disk.

(.SYS

files)

will

be

Prel~minary

CGC 7999

Page 1-39

DOS Manual

RENAME
Format:
RENAME



[1

[,]

RETURN

Where:
 is the name of an existing file,
 is the new name to be given to the file.


are options, described below.

RENAME alters a file's name. The primary name, secondary name,
or both, may be altered in the RENAME process.  must not
specify a drive number, since the file itself does not move from
the disk where it currently resides.
,If  specifies a
drive number, that number is ignored.
RENAME may also be used to change a file's attributes, such as
write-protection (see below). If you want to change a file's
attributes and leave its name the same, you may omit the 
name. It is NOT legal to omit both  and .
At
least one of these must be present.
RENAME is not allowed to change a file's password.
be used for this purpose.

COpy

should

If  contains wild cards, any files matching the pattern
are renamed. If  contains wild cards, characters are
pulled from the name of  to substitute for *'s in .
If  specifies only a primary name, all files with that
name (regardless of their
secondary
name)
are
renamed.
Likewise, if  specifies only a secondary name, a~~ files
with that name are renamed (regardless of their primary name).
This can result in more than one file having exactly the same
name. If this occurs, you can rename the files again (giving
them different names) by specifying the primary AND secondary
name of the file to be renamed. If  completely specifies
a file name, RENAME will only act on one file.
RENAME will not affect .SYS or .KIL files unless y.oo specify a
secondary filename of .SYS', .KIL, or .'. in .
RDlAME can
change a .SYS file to a .KIL, and can revive a ,.Xn. Lile into
its original type. BE CAREFUL.

Preliminary DOS Manual

CGC 79""

The option field may be used to alter
attributes (see DIR). Allowed options are:

-w

W

Write-protect
Write-enable

D
-D

Delete-protect
Delete-enable

E

Page 1-31

the

file's

status

Execute-only

If no options are specified, the file
retains
its
old
attributes. Note: for security reasons, RENAME will not remove
the execute-only status from a file. Once a file has the -estatus, that status may not be altered.

Examples:
RENAME AX BX

Rename file AX to BX, giving
it the same attributes AX had.

RENAME AX BX;W

Same as above, but writeprotect the file.

RENAME DATA OLDATA;WD

Rename DATA to OLDATA, writeand delete-protecting it.

RENAME ZOO;-W-D

Remove Wand D attributes from
the f.il e zoo.

RENAME SECRET;E

Make file SECRET execute-only.

RENAME XXll n/2

File XX on drive 1 is renamed
to YY; the -/2- is ignored.

RENAME XX

This produces -Argument Error.-

RENAME AB* CD*

Any file beginning with -ABwill now begin with -CD.-

RENAME can also change the name of a disk (the name given to
disk when it was FORMATted). Use this form of the command:
RENAME 12 Newname
The disk in drive 2 will be renamed to -Newname-.

the

CGC 79""

Preliminary DOS Manual .

Page 1-32

Preliminary DOS Manual

CGC 7900

Page 1-33

KILL
Format:
KILL



RETURN

Where:
 is the file to be KILLed.
The KILL transient changes a file's secondary name to .KIL
(except if the file is a .SYS file, it cannot be killed by KILL).
KILL is used to remove a file from Wactive Wstatus, and mark it
for eventual destruction with COMPRESS (see below).
After a
file has been killed, it is still recoverable, but is not
recognized unless specifically requested. The DIR command will
not display killed files unless the .KIL or .* pattern is
included. Most programs will ignore killed files.
.SYS files may be killed using the
their secondary name to .KIL (this
great care).

RENAME
should

command,
only be

to change
done with

After a file has been killed, it 1s still recoverable until the
disk is compressed (see COMPRESS). A .KIL file may be recovered
using the RENAME command, to change the secondary name to
something other than .KIL (.BUF, .SRC, etc.). After a COMPRESS,
the file is NOT recoverable.
If a pattern is used instead of a filename, ALL files matching
the pattern are KILLed.
Wild cards (*) may be included in the
pattern.

Preliminary DOS Manual

CGC 7998

Page 1-34

Examples:
KILL DATA

Kill the file named DATA

KILL DATA/2

Kill DATA on drive 2

KILL DATA$XY/2

Kill DATA on drive 2, passworded

KILL X*

Kill any file beginning with

KILL TEST

Kill any file with primary name TEST

KILL .SRC

Kill any file with secondary name .SRC

·Xl~

·X·

Preliminary DOS Manual

CGC 7930

Page 1-35

COMPRESS
Format:
COMPRESS

[$1

(/]

(iA]

RETURN

Where:
 is the two-character password of the files to
be COMPRESSed. If omitted, the password under
which you logged onto DOS will be assumed.


is the number of the drive containing the disk
to be compressed. If omitted, the disk which
contains the transient is compressed.

The COMPRESS transient disposes of all files whose secondary
name is .KIL (killed files). The space on the disk formerly
occupied by these files is now available for use again.
The
disposed files are NOT recoverable. COMPRESS also reclaims the
space formerly occupied by deleted files (see DELETE).
If a file is delete-protected, it
COMPRESS even if it has been KILLed.

will

If the iA option is given, ALL files
of their passwords.

are

not

be

compressed

affected

by

regardless

It is advisable to make a backup copy of important files, or of
the entire disk, before executing COMPRESS.
If COMPRESS is
interrupted by pressing Reset, by a power failure, or by
removing the diskette during COMPRESS, all data on the disk may
be lost.
COMPRESSing the hard disk (drive 3) may take several minutes.

Preliminary DOS Manual

CGC 79""

Page 1-36

Examples:
COMPRESS

Remove .KIL files

COMPRESS/2

Compress the disk in drive 2

COMPRESS/l /2

Compress the disk in drive 2, using the
COMPRESS transient from drive 1

COMPRESS $AB

Remove .KIL files under password -AB-

COMPRESS ,A

Remov~

.KIL files under ALL passwords

Preliminary DOS Manual

CGC 7900

Page 1-37

DELETE
Format:
DELETE



RETURN

Where:
 is the name of the file to be deleted.
DELETE removes a file from the disk directory.
This
immediately frees up the disk space formerly occupied
file. THE CONTENTS OF THE FILE ARE NOT RECOVERABLE.

process
by the

The DELETE command is different from KILL. KILL simply renames
a file with a .KIL secondary name, thus the file still exists.
After a file has been deleted, however, the disk directory no
longer shows the file's existance.
,
.

When the Disk Operating System is asked to create a new file, it
always takes the largest currently available chunk of disk
space. This means that it is not useful to DELETE a small file,
since the small chunk of space formerly occupied by that file
would never get used. DELETE is primarily useful for times when
you need to remove a large file (one occupying over 25' of the
disk, for example). DELETE allows you to reclaim the disk space
without going through the (time-consuming) process of KILLing
the file and then COMPRESSing the disk.
A pattern may be used in place of a
matching the pattern will be DELETEd.

file

name.

All

files

Example:
DELETE OLDdata

The space formerly occupied by deleted files is reclaimed when
the disk is COMPRESSed.
If you DELETE several small files
(going against the advice above), you will have to COMPRESS the
disk to make that space available for use again.
If a file is delete-protected, it cannot be deleted.

CGC 799"

.

Preliminary DOS Manual

Page 1-38

Preliminary DOS Manual

CGC79""

Page 1-39

BUFF
Format:
BUFF



RETURN

Where:
 is the name to be given to the file being
created by BUFF.
The BUFF command stores the contents of the Create Buffer into a
disk file. The secondary name .BUF is given to the file.
If
the file name already exists on this disk, the old file is
automatically KILLed •
• BUF files can be called back into the
DRAW transient.

Create

Buffer

with

the

Examples:
BUFF ANDWAX

Create a file called ANDWAX.

BUFFII FUDD/2

In this case the .BUF file is created
on a drive other than the drive where
the BUFF command resides.

When creating a picture to be
following hints may be helpful:

stored

as

a

.BUF

file,

the

1. Turn on CREATE before transmitting any other commands which
are necessary to set up the system for your picture.
For
example, if your picture will be drawn in the Bitmap, your .BUF
file should include the ·Overlay Off- and -Overlay Transparentcommands. Remember that the best .BUF files can be drawn
directly from DOS, requiring no setup by the user.
2. Turn the cursor off at the start of
makes a picture redraw faster.

your

.BUF

file.

This

~

Preliminary DOS Manual

CGC 7900

Page 1-48

DRAW
Format:
DRAW



RETURN

The file named  is called up from the disk and stored
the Create Buffer.  must have a .BUF secondary name.

into

After using the DRAW command, pressing the REDRAW key will cause
the picture in the Create Buffer to be redrawn.
Pressing XMIT
will cause the Create Buffer contents to be sent out Logical
Output Device 1, normally the RS-232 serial port.

Examples:
DRAW POKER

The file POKER.BUF is loaded into
the Create Buffer.

DRAW/3 Fliesll

The DRAW transient from drive 3 is
invoked to call up the file Flies.BUF
from drive 1.

NOTE: For best results, you are advised to pres~ the
TERMINAL key (leaving DOS and entering the Terminal
Emulator) before pressing REDRAW. If you do not press
TERMINAL before REPRAW, you will find that you are
still in DOS after your picture is redrawn, and
anything you type may obliterate your picture.
To
re-enter DOS after the picture finishes redrawing,
press SOFT BOar and pas. This will leave any picture
in the Bitmap intact.

If  was created on a CGC 7900 containing a different
number of image memory planes, the picture you generate may not
look the same as the original picture.
.

Preliminary DOS Manual

CGC 790"

Page ,1-41

APPEND
Format:
APPEND



RETURN

The APPEND command is similar to DRAW, except that the 
specified by APPEND is added to the end of the Create Buffer,
instead of replacing whatever was previously in the Create
Buffer. By performing a DRAW followed by one or more APPENDs,
several .BUF files may be concatenated. Then the BUFF transient
may be used to store the entire series as a single file.
....

Example:
DRAW Partl

load part one of a picture

APPEND Part2

add the second part

APPEND Part3

and the third part

BUFF ALLofit

store the whole thing

See also BUFF and DRAW.

CGe 791rJ1I .

PICTURE
Format:
PICTURE



[,l

RETURN

Where:
 is the name of a file to be created by
PICTURE. If a file with that name already
exists, the old file is KILLed.


is a hex number (s,ee below).

PICTURE stores an image from Bitmap memory into a disk file.
This requires up to two megabytes of storage, depending on the
number of Image Memory planes installed in your system, and thus
consumes a large amount of disk space. If the disk becomes full
while PICTURE is storing data, an error occurs and no data is
saved on the disk.
PICTURE also stores the contents of the Color Lookup
that the current colors on the Bitmap screen can be
later.

The file created by PICTURE has a .PIC secondary name.
Example:
PICTURE THIS

Table so
recreated

:GC

7900

Preliminary DOS Manual

Page 1-43

rhe optional argument  allows you to specify which planes of
Bitmap memory will be stored. You can store only the planes
~hich are applicable to your picture, and save disk space by
not
storing unneeded planes.  is a hexadecimal number between I
and FFFF. Each bit in  which is SET corresponds to a plane
~hich
will be stored.
The least significant bit of corresponds to plane 0, the most significant bit to plane 15. If
you enter more than four hex digits, only the last four are used.
Example:
- PICTURE FRAME

J 87 ~

::

The hex number 87 bas bits 0, 1, 2, and 7 set.
This command
stores the four planes which are normally installed in a
four-plane system. If your system contains only four planes,
this example is equivalent to using PICTURE without the optional
.
NOTE: Each plane stored by PICTURE occupies l28K bytes
of a disk, or $20000 hex bytes.
The -Free Lengthentry in the directory must be enough to accomodate
this length (plus 1024 bytes for the Color Lookup
Table), or PICTURE will generate an error message.

Example:
PICTURE BOOK ;7
This example stores only planes I, 1, and 2, a total of 385K
bytes.
If a picture was drawn on a four-plane system and the
blink plane was not in use, this command would store all
information necessary to reproduce the picture. Note that this
file would fit on a floppy diskette, but if four planes had been
stored, it would not fit.

For most applications, BUFF, DRAW and APPEND are much more
efficient methods of storing images.
See the preceding pages
for descriptions of these transients.
See also IMPLODE and
EXPLODE.

CGC

Preliminary DOS Manual

79S8

Page 1-44

REFRESH
Format:
REFRESH



RETURN

Where:
 is the name of a .PIC file to be brought in
from the disk, and displayed in image memory.
REFRESH is the opposite of PICTURE. REFRESH brings in up to two
megabytes of data from the disk and displays them on the screen.
The Color Lookup Table is also loaded by REFRESH.
See the
description of PICTURE for details.

If the .PIC file specified in the REFRESH command was created" on
a CGC 79SS containing a different number of Image Memory planes,
the image produce by REFRESH may not look exactly like the
original image stored by PICTURE.

Example:
REFRESH Yourself

CHROMATICS

D.t:

CGC 7900
Color Graphics Computer
Preliminary DOS Manual
(including Assembler
and Text Editor)
July, 1981

Page 1-45

Preliminary DOS Manual

:GC 7900

IMPLODE
Format:
IMPLODE



[;]

RETURN

Where:
 is the name of a file to be created by the
IMPLODE command. If a file by that name
already exists, the old file is KILLed.


is a hexadecimal number (see below).

IMPLODE stores an image from Bitmap memory,
However, IMPLODE uses a data compression
significantly reduce the amount of storage
Like PICTURE, IMPLODE also stores the Color

similar to PICTURE.
technique which can
a picture requires.
Lookup Table.

The file produced by IMPLODE has a .RLE secondary name.

The advantage of IMPLODE over PICTURE depends on the complexity
of the image, and in extreme cases, IMPLODE can actually use
more disk space than PICTURE. IMPLODE will display the number of
bytes it stored, and will also display the number of bytes
PICTURE would have used. You can then decide whether to try.
PICTURE instead.

 is a hexadecimal number which tells IMPLODE which planes to
store. It acts exactly like the optional  argument in the
PICTURE command. See the description of PICTURE.

Examples:
IMPLODE Baseball
IMPLODE CRT ;7

Preliminary DOS Manual

CGC 7998

Page 1-46

EXPLODE
Format:
EXPLODE



RETURN

Where:
 is the name of a .RLE file to be displayed
in Bitmap memory.
EXPLODE is the oPposite-- of· IMPLODE.
The data produced by
IMPLODE will be expanded back into its original form and
displayed in Bitmap memory.
The Color Lookup Table will be
restored to the colors it had at the time the picture was stored
by IMPLODE. See ~he description of IMPLODE for details.

If  was created on a CGC 7988 containing a different
number of Bitmap memory planes, the image produced by EXPLODE
may not look the same as the original image.

Example:
EXPLODE Dynamite

....

Page 1-47

Preliminary DOS Manual

CGC 7900

STORE
Format:
STORE





[+-]



[@]

[;]

RETURN

Where:
 is the name of the file to be created by STORE.
 and  are the starting and ending (hex)
addresses of the range to memory to be stored.
 is an address offset (hex) specifying the
difference between the address the data was
STOREd from and the address it will be loaded
into.  must be preceded by a + or sign.
 is the address at which execution of the data
must begin (assuming the data is a program)
 are described below.
STORE creates a disk file containing all bytes from the range of
memory  thru , inclusive.
The file created by
STORE may contain an absolute binary image of memory, or it may
be an image in executable form (readable by the DOS loader).
STORE decides which type of file to create, based on the
secondary name of .
STORE will allow you to specify any secondary name.
If you do
not specify a secondary name, the default secondary name of .SYS
is used and a load module is generated. If you specify .OBJ as
a secondary name, a load module is also generated.
Any other
secondary name causes an absolute binary image to be stored into
the file.

The arguments to STORE are affected
:

by

the

secondary

If the file type is .SYS, the default value for
zero, and the default value for  is .

name

of



is

Preliminary DOS Manual

CGC 790"

Page 1-48

If the file type is .OBJ, the default value for  and
 is zero. If the .OBJ file will be renamed to a .SYS
file,  must be specified at this time: a .OBJ file whose
 is zero cannot be executed.
If the file type is neither .SYS nor .OBJ,  and 
are not a1iowed. An absolute binary file is generated which
stores data in an unformatted form, storing just the bytes and
no addressing information. This type of file may be given any
secondary name, although .ASS is recommended.

A file created by STORE may be brought back into memory by FETCH
or DEBUG. If-STORE is used to create a .SYS file, the file may
be executed directly by typing its name as a DOS command.

Examples:
STORE/1 BOUSE.ASS/2 400" 4FFF
STORE Program 14000 14FFF-10"""@4400
Note that the + or - sign, and the @ sign, act as delimiters
the command line and should not be preceded by a space.

in

.p.

The option
makes a file ·proprietary· by setting the executeonly status in the file's attributes:
STORE SECRETS 11C3C 12AF0-10"00;P
....

The 7900 expects .SYS files to load and execute in the DOS
transient program area (TPA) or the DOS buffer.
The size of
these areas is set with the 7900 ·Thaw· command, but will
normally be at least 16K bytes. The DOS areas begin at memory
address $lC3C, and user programs should normally be arranged to
run in this area.
The STORE transient also runs in the OOS area, and would
overwrite any data in this area you are trying to STORE.
That
is the reason for the  parameter. Data to be STOREd can
be moved to a higher address with the Monitor ·Move Memory"
function, then the STORE command with an offset can be. used to
move the data back to its original addresses in the DOS area.

Preliminary DOS Manual

CGC 7930

Page 1-49

FETCH
Format:
FETCH



[] [+-]

RETURN

Where:
 is the name of the file to be loaded
into memory.
 is the address where the data from  is
to be loaded.  is required if the
file is NOT a .SYS or .OBJ file.
 is a displacement, to be added to the
normal load address of . 
is required for a .SYS or .OBJ file.
FETCH is the opposite of STORE.
It may be used to retrieve
bytes saved by the STORE transient, or to load a .SYS or .OBJ
file into memory.
FETCH will not load an execute-only file.
If the file read in by FETCH happens to over-write
areas of system memory, the system may hang.

important

Examples:
FETCH PGM.SYS/2+2000

FETCH BYTES.ABS lF000

Load the file PGN from drive 2,
at memory addresses 2000 (hex)
higher than it occupied when
it was STOREd.
Load the file BYTES into memory
beginning at address lF000 (hex)

Preliminary DOS Manual

CGC 7999

Page I-51

DEBUG
Format:
DEBUG



[]

RETURH

Where:
 is the name of a .SYS file to be
loaded i~to memory


are the arguments expected by the
.SYS file

DEBUG loads a .SYS file into memory, just as if the file had
been executed by DOS. After loading the file, DEBUG jumps to
the Monitor. If the file normally expects any arguments to be
present on the command line, they may be entered as .
DEBUG will not load an execute-only file.
To avoid having to use an offset when loading the .SYS file,
DEBUG relocates itself to the top of the DOS Transient Program
Area before loading . However, the TPA must be large
enough to accomodate both DEBUG and your file.
(DEBUG occupies
about 512 bytes.) If necessary, the ·Thaw· command can be used
to change the DOS memory allocation. See the 7999 User's Manual
for details.
Example:
DEBUG Process
DEBUG Gnats 6 12
In the second example, 6 and'12 are arguments
the program Gnats.

to

be

passed

to

Since the current Monitor (version 1.1) reloads the stack
pointer, it will not be possible for your program to execute a
normal return to' DOS. After using DEBUG to load your program,
you may use the Monitor to trace program execution up until the
point where your programatteapts to retUt'D to DOS.

Prel~rninary

CGC 790B

DOS Manual

Page 1-51

VERSION
Format:
VERSION



RETURN

VERSION displays the release date of the transients matching
. You may use VERSION to see whether you have the
latest set of transients from Chromatics, or to indicate the
release date of a transient when reporting a bug to Customer
Service.

You must enter at least the disk number as .
VERSION by itself causes an -Argument Error.-

Typing

Example:
VERSION /2

Display the release date of all
transients on the disk in drive 2.

Preliminary DOS Manual

CGC 7908

Page 1-52

SUMS
Format:
SUMS

RETURN

SUMS performs a checksum of all PROMs in the 7908 system.
This
is normally used as a check on the integrity of a PROM, or to
determine which version of firmware is installed in a system.
SUMS also displays the software revision level of the PROMs in
your 7900 system, by searching for the ASCII string ·VERi· in
each PROM. If your system contains PROMs version 1.1 or higher
(DOS version 1.4 or higher), SUMS will display the version
number of these programs.

Example:
SUMS

.~

Preliminary DOS Manual .

C 7900

Page 1-53

XREF
)rmat:
XREF

[A]


«file2> ••• , , etc. are ASCII files containing
an MC680"0 assembly language program.
 are described below.
~EF is a
program designed to be used with the Chromatics
IC68000 Assembler (discussed in Section 3 of this manual).
XREF
)roduces a cross-reference list of all labels in an MC68000
lssembly language source file. The line at which a label is
3efined is flagged with an asterisk (*).

(options> may include any of the following characters:
L

Transmit output to Logical Device I (normally
the screen)

T

Transmit output to Logical Device 1 (normally
the RS-232 serial port, assumed to connect to
a printer)

P

Print  lines per page (including 4 lines
used as a header)

W

Print lines up to  characters wide «m> may
range from 81 to 132)

-R

Don't cross-reference registers (AI, Dl, etc.)

If  are omitted, the default is ATP61Wl32+R.
This
causes listing to be directed to the printer, 61 lines per page,
132 columns per line, and registers are included in the XREF
listing.
Example:
XREF Program
XREF ALW85 Program

."

List on the screen, limit lines
to 85 characters wide.

•

CGC 79B8

Preliminary DOS Manual.

Page I-54

:GC 7909

Preliminary DOS Manual

Page 1-55

DOS ERROR MESSAGES
DOS will report errors which occur as a result of illegal
commands, faults in the disk system, or programming errors.
One
of the messages below will be displayed when a DOS error occurs.
When possible, DOS will display the drive number where the erroroccurred.

No index signal detected

No seek complete

Write fault
Drive not ready
Drive not selected
No track 000 detected
ID read error
Uncorrectable data error found during a read
ID address mark not found
Data address mark not found
Block not found
Seek error
No host acknowledgement
Diskette write protected
Data field error found and corrected
Bad track found
Format error
Invalid disk controller command
Illegal logical block address
Illegal function for the specified drive
Diagnostic RAM error
Disk controller not ready
Controller time out error
Unable to determine controller error
Undefined controller state
Controller protocol sequence error
Undefined load error state
Record cound error
Checksum error
Premature EOF during load
DOS buffer too small
Transient program size too small
End of file reached
File is write protected
Attempted to read thru density barrier
Attempted to transfer data on odd address

.....

CGC 79""

Preliminary DOS Manual

Unable to find requested file
Unable to create new file space
Unable to close requested file
Empty slot found
Unable to update the directory
No run address
Unable to find disk name
Argument error
Attempt to access a non-existant drive
Unable to initialize drive I
Unable to initialize drive 2
Syntax errorl Missing argument
Premature format termination
Error mapping routine not implemented
Unable to fetch this file
File is delete protected
File type error
File is execute only
File is to big to append
Insufficient stack size
/8 mode is not allowed in argument filenames
Undefined DOS error.

Page.I-56

:GC 79"0

Preliminary DOS Manual

Page 1-57

CGC 7988

-

Preliminary DOS Manual

Page 1-58

CGC 7ge0

Preliminary DOS Manual

Page 2-1

"",

SECTION 2 - THE EDITOR

CGe 79""

Preliminary DOS Manual

Page 2-2

....
•

CGC

Page 2-3

Preliminary DOS Manual

79"'"

INTRODUCTION TO THE EDITOR
The Chromatics' CGC 7900 Text Editor is a disk-based program used
for creating and maintaining text files. It is primarily used
in conjunction with the Assembler, for
creating
programs
executable by the Me68""" processor. The editor is also good
for workinq with other types
of
text
files,
such
as
correspondence or documentation.
This manual was, in fact,
written on a text editor.

The editor executes under DOS, the Disk Operating System, which
was described in Section One of this manual. If the DOS prompt
(a green asterisk) is not currently visible, press the ~ key.
Enter your password and press RETURN (or simply press RETURN).
Make sure that the system contains a disk which has the editor
on it, the program EDIT.SYS. Then type:
EDIT

RETURN

It may be necessary to specify the
containing the EDIT program, as:

number

of

the

disk

drive

EDIT/n
Where n is the number of the drive where EDIT.SYS resides.
This
will only be necessary if another drive, not containing the
editor, has been in use.

When the editor expects input, it will prompt you in one of three
ways. If the editor expects a command, the prompt is a 4-digit
line number followed by a question mark. If, it expects a line
of text to be inserted into the file, the prompt is a 4-digit
line number followed by an -I- and a question mark. If you are
in MODIFY mode, the prompt is a number followed by the letter -Mand a question mark.
8888

?

Command prompt

8888 I ?

Inse,rt prompt

8888 M ?

Modify prompt

CGC 7908

Preliminary DOS Manual

Page 2-4

The line number is a pointer position within the file.
The
editor refers to lines by number, and maintains an internal
pointer somewhere within the file. Commands are provided which
will explicitly move the pointer around, and many commands will
implicitly move the pointer. For example, if the pointer is on
line 3, and you LIST lines 3 thru 28 of the file, the pointer iJ!
now on line 28.
NOTE: When the edit pointer is at the beginning of the
file, the line number is displayed as "B". When it is
at the end, the line number is displayed as wEw.
When you see the command prompt, you may enter any of the legal
editor commands described in this manual.
The INSERT command
will take you out of command mode and put you into insert mode.
When you see the insert prompt, anything you type will be
inserted into the file at the current pointer position.
Hitting
the DELETE key will return you from insert mode to command mode.

Each of the commands in this section may be abbreviated to the
smallest number of characters which will uniquely identify that
command. For example, the OPEN command may be abbreviated to
the letter "0·, since no other command begins with that letter.
However, the command PRINT can only be abbreviated to two
characters, PR, so that it won't be confused with the PAGE
command (both begin with .p.).
In general it is safe to
abbreviate commands to two or three characters •

....

:GC 7900

Preliminary DOS Manual

Page 2-5

INLINE
-INLINE W is the standard subroutine used by the editor for
fetching a line of input from the keyboard.
This routine is
also used by other CGC 7900 programs, such as DOS.
INLINE
accepts a line of input, and allows editing, inserting and
deleting characters, and overstriking characters. When the line
is completed to your satisfaction, press RETURN.
Note: the
cursor can be anywhere on the input line when RETURN is struck,
but the entire visible line will always be accepted as input.

The left and right arrow keys move the cursor around within the
line currently being typed. The Home key moves the cursor to the
left edge of the current line. The cursor position is used to
determine where text will be inserted, or where other commands
will take effect.

INLINE supports the editing commands printed in blue on the
front of the cursor control keys: Insert Character, Delete
Character, Clear Line, Clear to End Of Line, Recall Last Line.
These blue functions are accessed by holding down the ~
(control) key and pressing the indicated key.
Del Char (Delete Character) removes one character at the current
cursor position. All characters to the right of the cursor move
left one position.
Clear Line erases the line currently being typed.
Clear EOL (Clear to End Of Line) erases all characters
current cursor position to the end of the line.

from

the

Recall (Recall Last Line) replaces the line currently being
typed with the last complete line that was typed. This function
is useful for repeating a command, perhaps altering it slightly
with the other functions. Press Recall more than once to bring
back earlier lines; this moves backward into the recall buffer.
Press SHIFT with Recall to move forward· in the recall buffer.

CGC

790"

Preliminary DOS Manual

Page 2-6

Ins Char (Insert Character) puts the routine into insert mode.
and
any
The character under the cursor begins blinking,
characters typed are now inserted, forcing characters to the
right of the cursor to move out of the way.
To leave insert
mode, use one of the arrow keys to move the cursor. This places
the routine in its normal (overstrike) mode, and any characters
typed now will simply overwrite existing characters under the
cursor.

INLINE is designed to be a general-purpose rQutine for ALL user
input in the CGC 7900.
The Appendix describes the calling
sequence for INLINE, for users who wish to use it in their own
programs. It is STRONGLY SUGGESTED that all programs use INLINE
to accept input from the user.
This means that all programs
will support character editing as described above, and the user
will become accustomed to using the same editing sequence for
all program input.

:GC 7900

Preliminary DOS Manual

Page 2-7

EDITOR COMMANDS
rhis section discusses the commands accepted by the editor.
E:ach of these commands m.ay be entered at the command prompt.

In each command, one or more delimiters may be present to
separate the various parts of the command. A delimiter may be a
space or comma. For convenience, we will always use a space in
our exampl es.

If the editor cannot interpret a command, or if for any reason
an error occurs during a command, the command line is re-printed
on the screen with the cursor positioned over the error.
You
may then edit the command line, using the INLINE editing
functions on the cursor keypad. This avoids retyping the entire
input line, and also illustrates exactly where the
error
occurred.

pre~iminary

CGC 7908

DOS Manual

Page 2-8

OPEN
Format:
OPEN



RETURN

Where:
 is the name of an existing disk file containing
ASCII text.  is assumed to have. the
secondary name .SRC, unless a different
secondary name is entered.
Before a.file can be edited, it must be OPENed as an input file.
The OPEN command searches for a specified file and returns an
error if the file cannot be located. If the file does exist,
OPEN simply returns to command mode.
Note: OPEN does not
actually cause any text to be read in from the file!
See GET
below.
.

The file is assumed to contain ASCII text.
Each line of the
file is terminated by a Carriage Return character, and no Line
Feed. The editor will provide a Line Feed after each Return
when LISTing or PRINTing the text.
Examples:
OP DOOR
OP WINDOW

...

OP ThatFile/2

Preliminary DOS Manual

CGC 7909

Page 2-9

GET
Format;
GET

RETURN

GET

<.> RETURN

Where:

<.> is a decimal number.
GET reads in text from the currently open input file (the file
most recently specified by OPEN). If the GET command is used
without an argument, enough text is read in to approximately
half fill the available memory. If a <.> is specified, only
that many lines are read in. The text is appended to the end of
the text already in memory.

If the GET command causes the entire file to be read in, the
message -End Of Input Data- is printed, and no more text may be
read in from the input file.

If the GET command causes memory to be filled with text, the
message -Workspace Full- is printed, and no more text is read
in. It is now necessary to PUT some text back on disk, to make
room for more of tpe file~
See PUT and PAGE for examples.
Note: Using GET without arguments is recommended, since it will_
never totally fill the workspace.

Examples:
GET
GET 39

Preliminary DOS Manual .

CGC 790.

Page 2-10

LIST
Format:
LIST

RETURN

LIST

<11>

RETURN

LIST

<11>

<12>

RETURN

Where:
<11> and <12> are line numbers.
LIST displays lines of text from the contents of memory.
If no
line numbers are entered, LIST begins at the current pointer
position. If one line number is given, listing begins at that
line and continues thru the end of the file.
If two line
numbers are given, listfng begins at the first line number
entered and continues thru the second line number.
LIST may be paused by typing a Control-S, and restarted with
Control-Q. LIST may be stopped at any time by pressing DELETE.
The output from LIST is always directed to Logical Output Device
0, normally the screen or a part of the screen.
Each line
displayed by LIST is shown with its line number, for reference.
Examples:
LI
LI 20"

Preliminary DOS Manual

CGC 7908

Page 2-11

PRINT
Format:
PRINT

RETURN

PRINT

<.1>

RETURN

PRINT

<.1>

<.2>

RETURN

PRINT performs the same function as LIST, but sends its output
to Logical Output Devices 0 and 1. Since Logical Output Device
1 is normally connected to a printer, this produces a hardcopy
of the lines listed. Unlike LIST, PRINT does not display line
numbers in front of each line.

Examples:
PR
PR 100 190

CGC 79SS

Preliminary DOS Manual

Page 2-12

INSERT
Format:
INSERT

RETURN

INSERT

<.> RETURN

Where:

<.> is a line number.
'--

INSERT takes the editor from command mode to insert mode.
in insert mode, the prompt is in the form:

While

NNNN I ?
The wI- indicates that material is being inserted into text.
If <.> is entered with the INSERT command, insertion begins at
the line specified. All lines from <.> up will move up in the
file to make room for lines being inserted.
If <.> is not
specified, insertion begins at the current pointer position.

INSERT is the most important command in the editor.
It allows
you to enter text to create a new file. While in inse~t mode,
any of the INLINE editing features may be" used, such as insert
and delete character.

Insert mode remains in effect until the DELETE key isstruek,
which time the editor returns to command mode.

at

Preliminary DOS Manual

CGC 7ge9

Page 2-13

NOTE: The INSERT command causes the line numbers of
part of the text in memory to be changed, as all lines
past the insertion move up in memory. It is advisable
to LIST the file after leaving insert mode, before
performing any operations which are dependent on line
numbers.

Examples:
IN
IN 15

If you enter a Mode code sequence (such as a ·Set Color·
command) into the input line, the sequence is displayed in
compressed form, using special characters. It is not executed
until you press the RETURN key. If you enter a tab character
(CTRL I) into the line, it too is displayed but not executed.
The Mode character resembles a double tilde (-), and the tab
character resembles a right-pointing arrow.
(These characters
are taken from the ·A7· character set, described in the CGC 7999
User's Manual.) Pressing RETURN will redisplay the input line
with all Mode codes executing as they normally would when
printed from a program. Tabs will be executed according to the
current tab stop spacing in effect (normally 4 characters apart).
Using the up and down arrow keys or the Delete Line function,
you can move from "INSERT mode into MODIFY mode. - Modify can also
be entered by giving the MODIFY command, as discussed next.

Page 2-14

Preliminary DOS Manual

CGC 7998

MODIFY
Format:
MODIFY

RETURN

MODIFY

<.> RETURN

Where:

<.> is a line number.
MODIFY is the editor's most flexible mode.
MODIFY, the editor's prompt is in the form

When

you

enter

NNNN M ?

and is displayed in magenta.
in magenta.

The current line is also

displayed

MODIFY allows you to use the INLINE editing features on existing
text in memory. You can insert or delete characters using the
labeled functions on the cursor keypad. When you have finished
altering a line, you must press RETURN to store that line in its
new form. If you move the cursor up or down using the arrow
keys, the line you modified will NOT be stored, but will return
to its previous condition.

Using the Insert Line and Delete line functions, you can move
between MODIFY mode and INSERT mode at will.
When in MODIFY,
the prompt will be displayed in magenta and will be in the form
-NNNN M?- While in INSERT mode, the prompt is in yellow, and is
in the form -NNNN I ?Pressing DELETE moves you back to command mode.
Examples:
MO

MO 25

CGC 7900

Preliminary DOS Manual

Page 2-15

When in MODIFY, as in INSERT, a special compressed form is used
to display Modes, tabs, and other control-characters.
In
MODIFY, the line containing the cursor is always displayed in
compressed form so that any control-characters in the line will
be visible and may be edited. Other lines on the screen during
MODIFY are displayed normallYJ only the line with the cursor isdisplayed in this special form.

CGC 7991

Preliminary DOS Manual

Page 2-16

DELETE
Format:
DELETE

RETURB

~ELETB

<.1>

RETURN

DELETE

<.1>

<.2>

RETURB

DELETE removes a set of lines from the text.
If DELETE is
entered with no arguments, only the current line is deleted.
(The curr'ent line is the line whose number is printed in the
prompt.)

If DELETE is entered with one argument <.1>, the single line
whose line number is <.1> is deleted. If DELETE is entered with
both <.1> and <12>, all lines within the range <11> thru <12>,
inclusive, are deleted.

NOTE: The DELETE command causes the line numbers of
part of the text to be changed, as all lines past the
lines deleted are moved down in memory.
After a
DELETE, it is advisable to LIST the file before doing
any other operations which are dependent on line
numbers.

Preliminary DOS Manual

CGC7909

Page

2-17

FIND
Format:
FIND

\\

RETURN

FIND

<11>

\\

FIND

<11>

<12> \\

FIND

<11>

<12>



RETURN
RETURN

\\

RETURN

FIND locates a string. The range of lines to be searched, and
the number of searches to perform, are specified in the command:
FIND with no arguments other than  begins searching
the current pointer position, and reports all occurances
 until the end of the file.

at
of

FIND with <11> is the same as above, but begins searching
line <11> rather than at the current pointer position.

at

FIND with <11> and <12> searches all lines
inclusive.

from

<11>

FIND with <11>, <12> and  begins searching at line
terminates when it reaches line <12> OR if it has
occurances of .

to
<11>,
found

<12>,
and


The backslash character W\W is used as a delimiter to define the
search string. Any non-numeric character (except WlW) could be
used as a delimiter, provided it does not occur in . The
terminating delimiter (just before RETURN) is not required.

Examples:
FI \8\

Find all zeroes from the current
pointer to the end of the file.

FI 1 999\.\

Find all decimal points in the file
(through line 999)

FI 1 999 l8\the\

Find up to 18 occurances of the
word Wthe W, between lines 1 and 999.

During a FIND, you may press CTRL S to pause the display, and
then CTRL 0 to continue. DELETE returns you to command mode.

Page 2-18

Preliminary DOS Manual

CGC 7998

SUBSTITUTE
Format:
SUBSTITUTE \\\

RETURN

SUBSTITUTE

<11>

\\\ RETQRN

SUBSTITUTE

<11>

<12> \\\ RETURN

SUBSTITUTE

<11>

<12>


\\\

RETURN

SUBSTITUTE

<11>

<12>

 

\\\

B~TQBH

SUBSTITUTE performs a search-and-replace
enter a number of options to
specify
substitution takes place:

function.
exactly

You
how

can
the

SUBSTITUTE with no arguments affects only the current line, and
if  is on that line, it is replaced by .
Only
one occurance of  will be replaced.
SUBSTITUTE with <11> affects only the line
one occurance will be replaced.

specified,

and

only

SUBSTITUTE with <11> and <12> begins at line number <.1> and
continues thru line number <.2>. If  is found on any
line, it is replaced by , but only the first occurance
of  per line will be affected.
SUBSTITUTE with <11>, <12> and 
 affects all. lines from
to <.2>, inclusive, and replaces 
 occurances per line.

....

<11>

SUBSTITUTE with <11>, <12>, 
 and 
 affects all lines from
<11> to <.2>, inclusive, replaces 
 occurances per line, but
begins at occurance  on each line.
The backslash W\W is used as a delimiter to define the beginning
and end of each string. Any non-numeric character (except W(W)
could also be used as a delimiter, provided it does not occur in
either  or .
The terminating
required.

delimiter

(just

before the

RETURN)

1s not

Preliminary DOS Manual

CGC 799"

page. 2-19

Examples:
Change the first occurance of
RA" to "B" on the current
line (if any).

SU \A\B\

SU

On line 54, change "123" to
·321" (one occurance at most)

54\123\321\

SU 1"9 2"8\me\I\

Change "me" to "I· everywhere
between lines 188 and 288 (not
more than once per line).

SU 188 2"8 99\me\I\

Same as above, but up to 99
times per line (effectively
changes all occurances on
each line in the range).

SU 1 188 1 2\this\the\

Between lines 1 and 188,
change the second occurance
"this· to ·the· on each line.

SU 1 188 99 2\this\the\ Same as above, but changes
all occurances EXCEPT the
first occurance on each line.
SU 18 55.\./.

Change backs1ash to slash
using a period as a
delimiter), once per line,
between lines 18 and 55.

SUBSTITUTE displays each line it changes.
To
abort
the
SUBSTITUTE process, press the DELETE key.
You will return to
command mode, and any lines which have not already
been
displayed by SUBSTITUTE will not be affected.
SUBSTITUTE can be very destructive, if not used carefully.
It
is good practice to use FIND before SUBSTITUTE, to see exactly
what will be affected by SUBSTITUTE. For example,
PI 1 99 1\A\

Find the first occurance of "A·
and display the line.

so \A\B\

Change "A· to "B· at thi' line

By using the Recall Last Line function, you can repeat these
commands as often as required, examining each occurance of
before changing it to "8".

two
"A·

Preliminary DOS Manual

CGC 7988

Page 2-28

LAST
Format:
LAST

RETURN

Each time the command prompt is printed, the current pointer
position is memorized. The LAST command moves the pointer to
its most recent location in memory. Using LAST more than once
will flip back and forth between the current location and the
most recent location.

Here is a sample session with the LAST command:
7988's Output
8818

?

User's Input
LIST 28 38

(Lines 28 thru 38 are listed)
8838

?

LAST

8818

?

LAST

8838

?

Preliminary DOS Manual

CGC 79"9

Page 2-21

PUT
Format:
PUT

RETURN

PUT

<11>

RETURN

PUT

<11>

<12>

RETURN

PUT removes text from memory, and writes it back to the disk.

If PUT is entered with no arguments, all text in memory is
written out to the disk. If one argument <11> is entered, all
lines from the beginning of text thru line <11> are written out
to the disk.

If two arguments are entered, only lines between line
<11> and line number <12> are written out to the disk.

number

PUT is primarily useful for dividing up a file into smaller
files. By doing a PUT followed by a CLOSE, a new file is
created which contains only the lines which were POT.

PAGE and EXIT are more general-purpose
editing session.

Examples:
PO
PO 69 99

commands

for

ending

an

Preliminary DOS Manual

CGC 7999

Page 2-22

CLOSE
Format:
CLOSE

RETURN

CLOSE



RETURN

CLOSE enters the output file into the disk directory, and closes
the file. If CLOSE is entered without a , the new
file has the same name as the old file; the editor will then
automatically KILL the old file.
The
If a  is specified, the new file has that name.
file will have .SRC as a secondary name unless you specify a
different secondary name.
Once a file has been closed, either by CLOSE or by EXIT, it
exists on the disk and can be re-opened by OPEN as an input file.

Examples:
CL
CL MIND
CL NEWFILE

PAGE and EXIT are more general-purpose
editing session.

commands

for

ending

an

Preliminary DOS Manual

3C 7900

Page 2-23

PAGE
ormat:
PAGE

RETURN

~he PAGE
~o large

command is used when editing large files. If a file is
that it cannot all fit into memory at once, it is
lecessary to bring in a portion of the file, edit that portion,
~hen go on to the next.
PAGE dumps all of the text in memory
~ack to the disk, then brings in enough text from the input
file
to half fill the available memory.

PAGE is thus equivalent to doing a PUT of
followed by a GET.

Example:
PA

all

text

in

memory,

Preliminary DOS Manual

CGC 7998

Page 2-24

DRIVE
Format:
DRIVE

(N)

RETURN

The output-from the editor normally goes onto the same disk from
which the input file was read.
You may alter this with the
DRIVE command, forcing the editor's output onto another disk.
DRIVE causes the editor to create a new output file, on the
specified disk.

Example:
DR 2

If you have already written some text to the output file, using
PAGE or PUT, DRIVE is not allowed until you CLOSE the currently
open output file. (If it were allowed, the text you had written
to the disk would be lost.)

Preliminary DOS Manual

:GC 7900

Page 2-25

EXIT
Format:
EXIT

RETURN

EXIT



RETlJRN

EXIT is the proper way to end an editing session.
EXIT first
PUTs all text in memory onto the disk.
Then it performs a
series of GETs and PUTs (if necessary) to insure that the entire
input file has been written to the output file.
When no text
remains in the input file, the output file is closed.
If EXIT is entered with no , the output file has the
same name as the input file.
The editor then automatically
KILLs the old input file.
If EXIT is entered with a , the output file is given
that name. The file will have .SRC as a secondary name unless
you specify otherwise.
Example:
EX
EX RAMP

Preliminary DOS Manual

CGC 7991

Page 2-26

ABORT
Format:
ABORT

RETURN

The ABORT command ends an editing session, but does
the output file. If any changes had been made in the
changes are lost.

not close
file, the

ABORT is used if you decide that you don't want to alter the
file after all. If you had been using the editor simply to
examine a file (rather than making changes), ABORT would be the
logical way to end the session.

Example:

AB
NOTE: Pressing the nas, MONITOR, or TERMINAL keys will
also result in leaving the editor.
To Ie-enter the
editor after an abort, execute the key sequence
SHIFT USER W
this will -warm-start- the editor,
memory intact.

with

the

data

in

:;C 7900

Preliminary DOS Manual

Page 2-27

CGC 7999

Preliminary DOS Manual

Page 2-28

CGC 7909

Pre~iminary

DOS Manual

Page 3-1

"'.

SECTION 3 - THE ASSEMBLER

CGC 790e

Preliminary DOS Manual

Page 3-2

CGC 7999

Preliminary DOS Manual

Page 3-3

INTRODUCTION TO THE ASSEMBLER
The Chromatics MC68099 resident assembler is used to produce
source
machine-readable object code from assembly language
files.
The assembler executes under the
Chromatics
Disk
Operating System, described in Part I of this manual.

The full MC68090 instruction set is supported by the assembler.
In this manual, it is assumed that you understand the MC68990
processor architecture, as described in the Motorola MC68900
Userls Guide (available from Chromatics). The examples provided
in this manual are intended only to demonstrate .proper syntax,
and do not necessarily show useful programming techniques.

It is assumed that you are familiar with basic
techniques used in the CGC 79901 if not, consult the
Userls Manual before attempting to use the assembler.

operating
CGC 7900

Page 3-4

Preliminary DOS Manual

tGC 7999

ASSEMBLER COMMAND LINE
FiQrmat:
ASMB

["]



ASMB

["]



["]

RETURN



•••

RETURN

Where:
,, etc. are the names of source
files to be assembled
 are characters which specify assembly
options (see below)
Yhe ASMB

command invokes the file ASMB.SYS, the Chromatics
resident assembler. The ASMB command must be entered at
the DOS prompt, the green asterisk (*).
~C68999

The assembler expects its input files to be in ASCII
Input files must have the secondary name .SRC.

text

form.

The assembler produces an output file of type .SYS, which may
directly executed by DOS. If you enter the command line

be

ASMB PROGRAM
and press the RETURN key, the file PROGRAM.SRC would
assembled and an output file named PROGRAM.SYS
would
produced. This .SYS file can be directly executed by typing
name as a DOS command:
PROGRAM

be
be
its

GC

Preliminary DOS Manual

79""

Page 3-5

rhen the assembler closes its output .SYS file, any old .SYS
:ile with the same name is KILLed.
Thus, a program can be
!dited, assembled, re-edited and re-assembled any number of
:imes, but only the most recent version of the source and object
:ode will be active on the disk.

Several options are available to control the assembly and the
output listing. The option field is indicated by the ·caratcharacter,
The options may be entered in any order.

A.

C
-C

T
-T
L

Close output file, producing an executable program
file as output.
Do not close output file.

Type

listing on

prin~er

(through Logical Output 1).

Display listing on screen (through Logical Output ").
Follow LIST/NOLST commands in source file. The
listing is on until a NOLST is encountered.

+L

Force listing ON regardless of source file.

-L

Force listing OFF regardless of source file.

The default conditions for options are C and L.
If no options
are specified, this will result in the output file being closed,
listing on the 79"" screen, and listing being controlled by LIST
or HOLST commands in the program source file.
If you do not specify any options, you must not enter
(A) •

the

carat

Preliminary DOS Manual

CGC 79""

All options are valid at the start of the command line, before
the first file name . You may repeat any of the -Loptions prior to other files, in order to control listing of the
various files indi~idually.

Examples:
ASMB TEST

Assemble the file TEST, close output
file, listing on the screen. Output
file is named TEST.SYS.

ASMB A_C TEST

Assemble, list to screen, do not close
output file.

ASMB A_L TEST

Assemble and close, no listing.

ASMB AT-C+L TEST

Assemble, list on printer, do not
close output file, listing ON.

ASMB AT_L TESTI A+L TEST2
The last example assembles the program which is contained in
both files, TESTI and TEST2. The output file is clos~d, and is
given the name TEST2.SYS. This file is created on the same drive
which contained the file TEST2. Listing is supressed for file
TESTI and is forced on for TEST2. (Options other than the -Lfamily would not be valid prior to TEST2.)
.....

If a program is contained in more than one file, each
have its own END statement.

file

must

Preliminary DOS Manual

:;C 79""

Page 3-7

SOURCE FILE FORMAT
he text editor is used to create program source files, which
re processed by the assembler. Source files have a secondary
ame of .SRC, and are stored in ASCII text form.

~he

general form of a line in the source file is:
[

[]

[]

rhe four fields may be separated by spaces or tabs.

 is optional. If included, it must be alphanumeric, from
one to twenty-four characters. Other lines of code may refer to
this line by referencing .
 is required. It must be a legal instruction mnemonic,
as defined in the MC680"" instruction set, or it may be a
pseudo-instruction recognized by the assembler.
This manual
includes descriptions of the pseudo-ops available.
Consult
Motorola literature for details on the MC680"" instruction set.
(operands> are the arguments to the instruction.
instructions require different arguments.

Different

(comments> may be included on any line, at the programmer's
convenience. It may be useful to use a color-code at the
beginning of a comment, to distinguish different sections of
a program.

In addition, any line beginning with an asterisk (*) is
and whole-line comments may be included in this way.

ignored,

The first (or only) source file in a program will' generally
begin with an ORG statement, to initialize the Internal Program
Counter (IPC). Each source file must end with an END statement •

=···-....

_~·

.... ·.·_ ..

~_."

..

_"'~

.. , __ ._,.·.u..

_~_

.• __ '_

.._

Preliminary DOS Manual

CGC 7908

Page 3-8

"LABELS
Labels always begin in the first column (character position)
a line of code.
If the first character in a line is a space
tab, the line does not contain a label.

of
or

A label may contain any upper or lower case letter, A-Z or a-z,
or digits 0-9. It may contain up to 24 characters, and all
characters are significant. Opper and lower case characters are
distinct; that is, the. l~bels AB and Ab
are
considered
different. A label must begin with a letter.
A label is assigned the value of the IPC at
where the label occurs, unless the instruction
(see Pseudo-Instructions).
Certain reserved words have special meanings
and may not be used as labels. They are:
D8
AI
SP

Dl
Al

OSP

D2
A2

CCR

D3
A3

SR

D4
A4
IPC

D5
AS

to

the instruction
is EgO or SET

the
D6
A6

assembler,

D7
A7

It is possible, but not wise, to use an instruction mnemonic
a label.

-

as

Preliminary DOS Manual

CGC 7900

Page 3-9

INSTRUCTIONS
The instruction field is separated from the label by a space or
a tab. If a line does not contain a label, the instruction must
be preceded by a space or tab to separate it from the beginnin9
of the line.

instruction will either be a member
of
instruction set, or a pseudo-instruction which is
the assembler as an order to do somethin9.

An

the
MC68000
recognized by

If an instruction is a le9al MC68000 op code, it may have a data
size associated with it.
Certain MC68000 instructions can
operate on different data sizes: Byte (8 bit), Word (16 bit), or
Lon9 (32 bit). For these instructions, the desired. data size
may be specified by appending the characters
or
to the op code. The default ',data size of Word (16 bit) is
assumed if the data size code 1s omitted.

-.B-, -.W-

-.L-

If an instruction does not have a variable data size associated
with it, the characters B, W or L may NOT be appended.

Examples:
MOVE

Dl,D2

Word size is assumed by default.

MOVE.B

D3,D4

Byte size is declared.

LEA

(Al),A2

Lon9 word size 1s required for this
instruction; a data size code would
not be permitted here.

Preliminary DOS Manual

CGC 79""

Page 3-1"

OPERANDS
The operands, if any, follow the instruction.
Operands are
separated from the instruction by a space or tab. If more than
one operand is present, they are separated by commas.

Instructions which
Most instructions have one or two operands.
use two operands consider the first to be a "source" and the
second to be a "destination", as:
MOVE.W 01,05
ANDI.L

t$7F, (A2)

SUB.W

OS, (A3) +

Move l6-bit data from 01 to 05.
Get 32-bit data from the address
pointed to by A2; AND it with
immediate data $7F (hex); then put
the result back where we got it.
Subtract OS from the l6-bit word
'- pointed to by A3; put back the
result, then increment A3 by 2.

The same terminology of "source" and "destination" is applied
compare operations. Note that the "destination" is compared
the "source", not the other way around:
CMP.L
BGT

AS,A!
Somewhre

Is Al greater than AS?
If YES, do the branch.

to
to

Preliminary DOS Manual

CGC 7900

Page 3-11

COMMENTS
Any line may contain a comment field. The comment field may be
separated from the remainder of the line by a ·Set Color·
command, which will cause the comment to be displayed in a
different color from the program code. The color code is not
necessary in most cases (except as mentioned in the note below),
but it will improve the legibility of your programs.
Color
codes in a source line are never transmitted to a printer.
"-

To insert a color-coded comment into a line of program source
using the 7900 editor, first separate it from the rest of the
line by a tab (CTRL I) or spaces. Then press ~, followed by a
color key. When displayed by the editor in response to LIST,
the color will be executed as typed. When in MODIFY or INSERT
mode, the line containing the cursor is always displayed in
compressed form, using special symbols for control-characters.
A typical statement might normally appear as:
LABEL

EQU

value

This is a comment

If a color code had been'typed before ·This·, the comment field
would appear in that color. In MODIFY mode, or when entering
the line in INSERT mode, the same line would appear as:
LABEL-EQU-value--C6,This is a comment
The tab character is abbreviated with a right-arrow symbol, and
'the Mode character is abbreviated with a double tilde.
This
example uses color number 6, or yellow, as the comment color.
You may wish to'define a Function Key to be the equivalent of a
·Set Color· command.
If a color code (or any Mode sequence) is present in a source
line, the assembler assumes that it delimits a comment, and does
not attempt to parse any items beyond the Mode character.
NOTE: Certain op-codes will accept an
indefinite
number of arguments (Example: Define Constant, DC).
In these cases, the assembler will continue to parse
arguments from the source line until it reaches a Mode
character or a carriage return.
If you include a
comment in a source line of this type, you . MOST
delimit the comment with 'a Mode code, or the comment
'will be assembledl Note that the END pseudo-op also
accepts a variable number of arguments (zero or one
expressions). A comment on an END statement should be
delimited with a color code.
,"

CGC 7ge8

Preliminary DOS Manual

Page 3-12

X;C

7908

Preliminary DOS Manual

Page 3-13

INSTRUCTION EXAMPLES
rhis section discusses the instructions available in the
instruction set, and provides examples.

MC68000

Preliminary DOS Manual

CGC 79BB

Page 3-14

ARITHMETIC
Format:


,

Add, subtract, multiply, divide, and negate are
provided.
Multiplication and division may
use
signed
or
unsigned
arithmetic. BCD operations of add, subtract and negate are
provided.
Operations may use the X (extend) bit of
the
condition codes for multiprecision operations.
CLR sets an
operand to zero. Test, and Test-And-Set, set the condition codes
according to an operand's value. TAB is also used to synchronize
processors in.a multiprocessor system.

Examples:

....

ADD.L

(Al),02

Add the 32-bit data pointed to
by Al, to the contents of 02,
results in 02.

MULU

03,04

Multiply, with unsigned numbers,
04 by D3, results in 04.

SUB.W

.5,01

Subtract 5 from the lower 16 bits
of Dll put the result in Dl.

OIVS

D5,09

Oivide OB by 05 using signed
numbers. Put the result in DB.
(See Motorola literature for
details of this instruction.)

CLR.B

(A3)

Zero the byte whose address is
in A3 •

TST.W

D4

Set condition codes according to
the low 16 bits of D4.

Preliminary DOS Manual

CGC 7999

Page 3-15

COMPARE
Format:
CMP.

,

CBK

,Dn

 is subtracted from  and condition codes are set
accordingly. The conditional branch instructions are arranged
so that a -Greater Than- condition tests true if  is
Greater Than .
Neither  nor  is altered by a compare.
CBK causes a processor trap to occur if the contents of
Dn are less than zero or greater than .

register

Examples:
CMP.L

(A3) ,01

BLT
BGT

Labell
Labe12

Compare Dl to 32-bit data at
address AJ,
Branch here if 01 < (A3)
Branch here if 01 > (A3)
Else 01 == (AJ) I (Profound ••• )

CBK

'$199,09

trap if D9 > 256.

Page 3-16

Preliminary DOS Manual

CGC 798"

LOGICAL
Format:
,


Logical operations
provided.

of

AND,

OR,

Exclusive

OR,

and

NOT

are

Examples:
ORI.W

'1, (A6)

OR immediate data (1) with the
word whose address is in A6.

AND.L

D4,D3

Logical AND P4 with 03 (32 bits),
results in D3.

SHIFT AND ROTATE
Format:


 , ,.

Arithmetic and logical shifts and rotates are provided.
The
shift count may be specified by immediate data or by a register.
If the effective address of the destination is in memory, only
one bit position at a time may be shifted. Rotates may use the X
(extend) bit •

....
Examples:
ASR

(A8)+

Shift the data pointed to by AS,
one bit right. Word size is implicit
since no other size is allowed here.

ROL.L

'3,01

Rotate Dl 3 bits left, using all
32 bits of data in the register.

Preliminary DOS Manual

:GC 7909

Page

3-J.1

BIT OPERATIONS
Format:


,

A single bit may be tested and/or modified in a register or
memory location. The condition codes are always set according
to the state of the bit BEFORE any modification. If  is a
register, any of the 32 bits may be tested.
If  is an
effective address in memory, the operation may only be byte
size, and therefore only bits S through 7 may be tested.
Examples:
BTST

IS,StatWord

Check bit S in memory location
StatWord. Set condition codes.

BCRG

'18,DS

Set condition codes according to
bit 18 in OS, then flip that bit.

EFFECTIVE ADDRESS
The effective address of an operand may be computed
into an address register, or pushed onto the stack.

and

loaded

Examples:
PEA

RetnBere

Push the effective address of the
label RetnBere onto the stack. The
next RTS (Return from Subroutine)
will cause a jump to this address.

LEA

Displ(AS,Dl.L),A6

Load the effective address
found by adding AS to Dl
and to the value Displ,
put the result 1noA6.

Preliminary DOS Manual

CGC 7999

Page 3-18

MOVE DATA
Format:
MOVE.

,

~OVEQ.L

l,Dn

EXG

Rn,Rn

Move operations transfer data between registers and/or memory.
MOVEQ (Move Quick) is a special form which will load small data
into the low byte of a data register,
sign-extended into the
upper three bytes. Using MOVEQ,  must be between -128 and
+127. EXG exchanges the 32-bit contents of two registers.

The MOVE instruction is very flexible, as all addressing modes
may be used for  and most modes are also valid for
.

Examples:
MOVE.L

Dl,(A3)+

Move 32-bit data from Dl to
the address pointed to by Al.
Postincrement Al.

MOVE.B

I' ',D7

Put a space character into the
low byte of D7.

MOVEQ.L

I$F,DS

Move a hex F (15) into DS.
MOVE would work here, but would
take extra object code.

EXG

Dl,D5

Exchange register contents"

Preliminary DOS Manual

3C 7900

Page

3-~~

MOVE MULTIPLE
ormat:
MOVEM.

,

,

10ve Multiple stores several registers into memory or retrieves
:hem with a single instruction.  of word (.W) or long
(.L) is allowed.
 may include the names of data
or address registers. A hyphen implies that all registers
~ithin the hyphenated list should be saved, while a slash implies
that only the listed registers should be saved:
Dl-D7

registers 01 thru 07, inclusive

OS/Al/A3

registers OS, Al, and A3 only

The registers must be specified in ascending order, with
registers listed first. MOVEM makes it easy to "push" and
·pop· a set of registers for temporary storage.

Examples:
MOVEM.L

D0-A6,-(SP)

Push all regist&rs-D0 thru
07 and A0 thru A6 onto the
stack (pointed to by SP).

MOVEM.L

(SP)+,00-A6

Restore these registers.

MOVEM.W

DS-07/A0,Storage

Store registers A0, OS,
06 and D7 into words of
memory beginning at
label Storage.

data
then

Preliminary DOS Manual

CGC 7908

Page 3-28

BRANCH, JUMP
Format:




JMP is an Unconditional transfer to an absolute address. JSR is
a subroutine call to an absolute address.
There
is
no
instruction to conditionally transfer to an absolute address.
BRA and its variations are relative transfers.
The assembler
computes the relative distance between the current IPC and the
destination operand,
and
ent~rs
this
as
the
relative
displacement in object code. A branch must always reference a
label within plus or minus 32767 bytes of the current IPC.
(See
also ·short branch· below.)
Branches may be conditional or unconditional.
Conditional
branches are in the form Bcc, where cc is the condition under
which the branch is taken. For example, BEQ will branch if the
condition codes show the last comparison came out EQual (zero).
Valid conditional tests are:
CC carry clear
CS carry set
EQ equal
GE greater or equal
GT greater than
HI high
LE less or equal

-

LS low or same
LT less than
MI minus
NE not equal
PL plus
VC no overflow
VS overflow

The conditional tests PL, MI, GE, LT, GT, and LE treat operands
as sign-extended numbers. If the high bit of the operand is
set, the operand is negative. The other conditional tests treat
operands as unsigned numbers.
Motorola
MC68000
processor
literature lists the flags examined by each of the conditional
tests above.

Preliminary DOS Manual

CGC 79"9

Page 3-21

A branch may be in the form BRA.S, where the "S- implies
"short-. Since these are relative branches, a short branch may
only be used to transfer to a location within plus or minus 127
bytes of the current pc. Using short branches whenever possible
saves time and space. The assembler will automatically convert
a branch to a short branch if possible. If the program contains
a short branch to an address more than 127 bytes away, an error
occurs.
Branches to a subroutine (BSR and its variations) push the
return address onto the stack. A short form of subroutine call
(BSR.S) is also provided. A RTS (Return from Subroutine) pops
this address off the stack.

Examples:
JMP

Overhill

Unconditional transfer to label
Overhill.

BRA

Faraway

Unconditional Branch to label
Faraway.

BRA.S

Nearby

Unconditional Short branch to
label Nearby.

BLT.S

Wasless

Short, conditional branch to
label Wasless, occurs if condition
codes show the last comparison
came out -Less.Than- (LT).

BSR

Subpgm

Call to a subroutine.

JSR

Farsub

Call to a subroutine which is
more than 32767 bytes away, or
which is accessed through an
absolute address (such as a jump
table).

Preliminary DOS Manual

CGC 7908

Page 3-22

DECREMENT AND BRANCH
Format:
DBee

Dn,(loeation)

The DBee instruction will implement a loop in a very simple
fashion. It first tests the condition codes specified by ee. If
this test is true, the instruction falls through (does not
branch or perform any other operation).
If the test is NOT true, the lower word of data register (Dn) is
decremented by one. Then if the lower word of the register does
not contain a -1, the branch to (location) is taken.
(location)
must be within a 16-bit displacement of the DBce instruction.
The loop will therefore conti~ue ~ti1 either (1) the test in
is true, OR (2) the lower word of Dn contains -1.

ce

Example:

Loop

MOVE.W

11881,D1

Loop up to 1001 times

TST.B

(A2)+

Is memory • I here?

DBEO

D1,LOOp

If not,· look again until
D1=-1 or the test came out
-EO-, meaning ·(A2)=1

A special form of this instruction is DBRA. No condition
are tested by DBRA; the loop simply continues until the
word of Dn is -1.

codes
lower

Preliminary DOS Manual

CGC 7900

Page 3-23

SET
Format:
See



The byte specified by 

ORG.L



ORG is used to set the -origin- of the code generated by the
assembler. ORG loads a value into the Internal Program Counter
(IPC).
When using the (default) ORG form,
all
absolute
addresses are assembled in -absolute short- form, which confines
them to values between $"""" and $7FFF, and between $FF8""" and
$FFFFFF.
ORG.L
In the CGC 79"", the -long W ORG.L is more commonly used.
forces all absolute addresses to long form, which allows access
to the entire 79"" address space (~"""""" to $FFFFFF).
(The exception to this rule occurs if a symbol name is suffixed
with a w.Ww or w.Lw specifier. In this case, the specifier is
used and the ORG type is overridden.)
Examples:
ORG.L

PROGSTART

ORG.L

$lC3C.

DOS expects programs to run in the DOS Transient Program Area,
which begins at $IC3C. Your programs should normally be ORG'ed
at this address.

ORG may be used in several places during a program, if desired.

Preliminary DOS Manual

Page 3-31

EQU (EQUATE)
Format:


EOO



EQU equates a label to a value, the value of .
 is required in this context, for the EQU statement is
meaningless without a label.  may contain constants
or other labels which have been previously defined in the
program.

Examples:
BexNum

EQU

$0A0A

Gold

EQU

Silver+32

HERE

EQO

IPC

The last example equates the label wHERE w to the value of the
assembler's Internal Program Counter. The IPC always has the
value of the address for which code is currenty being generated.
Note the equivalence of the following two pieces of code:
SUBRT- MOVE.L

Dl,D3

SUBRT

IPC
Dl,D3

and,
EQO
MOVE.L

Either of these two sections would generate
code if used in the same place in a program.

identical

object

Preliminary DOS Manual

OGe 79B8

Page 3-32

SET
Format:


SET



SET assigns the value of 
to
.
The
difference between SET and EOO is that a label defined by SET may
be re-defined later in the program by another SET.
A label
defined by SET may not be defined by EOO, nor may it be used in
the label field of a line of,qode.

The rules for  are the same as for EOO.

Preliminary DOS Manual

:GC 7911

Pa~';.;

3-3J

DC (DEFINE CONSTANT)
Format:
DC.B

(expression> [,(expression> ••• ]

DC.W

(expression> [,(expression> ••• ]

DC.L

(expression> [,(expression> ••• ]

The DC pseudo-ops generate bytes, words or long-words
whose value is equal to (expression>.
More than one
may be defined by a single DC statement, by using a
expressions.

of code
constant
list of

Examples~

DC.B

'hi'

DC.B

I,0,l,-S,$A9,$FF

DC.W

$4S04,7001,-l,'WO'

DC.L

$l81lA4C9,'LONG'

NOTE: The DC.B pseudo-op may cause the IPC to end up
on an odd address after assembling an odd ·number of
bytes. This will cause instructions following the
DC.B to assemble on odd addresses, which is illegal.
See DS.L below for a way around this problem.
.

If the expression does not evaluate to a number within the
range specified (8, 16 or 32 bits), an ·S· error occurs.

size

Preliminary DOS Manual

CGC 79""

Page 3-34

When entering an ASCII string in a DC.W or DC.L statement, the
string packed into memory as one character per byte. If an odd
number of bytes is entered, the last word (or long word) is
zero-filled on the right, to the nearest word (or long word)
boundary.
Examples:
DC.W

' A'

would put

'A' ,"

DC.W

'ABC'

would put

'A','B','C',"

DC.L

' A'

would put

'A',",","

DC.L

'AB'

would put

'A' ,'B' ,","

in memory
in memory

in memory
in memory

.'

-~.--

Preliminary DOS Manual

CGC 7903

Page 3-35

OS (DEFINE STORAGE)
Format:
OS.B



os.w



OS.L



The OS pseudo-ops reserve space by advancing the IPC past a
number of bytes, words or long words.
 determines
the number of bytes, words, or long words skipped.
No code is
generated by OS pseudo-ops.

Examples:
OS.B

14

OS.L

1

NOTE: The DS.B and OC.B pseudo-ops may cause an odd
number of bytes to be assembled. This causes the IPC
to end up on an
odd
address,
and
subsequent
instructions will be assembled on odd addresses, which
is illegal. To avoid this problem, always follow DC.B
ana OS.B pseudo-ops with a wOS.L 3 n ~ine.
This
insures that no machine instructions will begin on odd
addresses. OS.L used with an argument of zero bumps
the IPC to the nearest even boundary.
Example:
OS.B
OS.L

9
8

Reserve some space, then
align IPC to a word boundary.

Preliminary DOS Manual

CGe 7998

Page 3-36

END
Format:
END

[]

The END statement tells the assembler that no more lines of
source code exist in the file. Each file must end with an END,
or the assembler will attempt to read past the end of the file
and an error will occur.

The last (or only) source file in a program may have an address,
, in the argument field of its END statement.

tells DOS where to begin execution of the program, if and when
the program is executed as a .SYS file. If  is omitted,
the assembler assumes the program begins at the beginning, and
will set  by default to the first instruction in the
program.

Preliminary DOS Manual

CGC 79B"

Page 3-37

PAGE
Format:
PAGE
The PAGE pseudo-op tells the assembler to output a form-feed
during the assembly listing. It may be used to break up a
listing into convenient pieces.
PAGE has no effect on the
object code.

LLEN
Format:
LLEN



LLEN instructs the assembler that it may print lines containing
up to  characters. The default value for  is
85, corresponding to the width of the OGC Overlay screen.
 may be set to suit the width of your printer, and must
be a number between I and 255.

Example:
LLEN

132

Preliminary DOS Manual

CGC 790"

Page 3-38

NOLST
Format:
NOLST
NOLST turns off the assembly listing. It is typically used in
conjunction with LIST, to cause only selected parts of the
program to be listed during assembly.

LIST
Format:
LIST
LIST resumes the assembly listing, following a NOLST.
LIST
in effect by default, unless a NOLST has been encountered.

is

Preliminary DOS Manual

CGC 7900

Page

3-3~

ADDRESSING MODES
The MC68000 provides a large number of effective address modes,
which define the source and/or destination operands in an
instruction. This section discusses and provides examples of
each of the addressing modes supported by the MC68000, and the
proper syntax for their use.

REGISTER DIRECT
Format:
where n is a number, S thru 7.

An or On

This mode operates directly on the C9ntents
thru 07 or AO thru A7.

of

a

register,

DO

Examples:
MOVE.L

A1 ,A4

Move the contents of register Al
into register A4 (32 bits).

ADD.W

DS,03

Add the lower 16 bits of the contents
of DO to the lower 16 bits of the
contents of 03. Put the result into
the lower 16 bits of 03.

Preliminary DOS Manual

CGC 7908

Page 3-48

ADDRESS REGISTER INDIRECT
Format:
(An)

where n is a number, 8 thru 7.

This mode operates on the memory location
the specified address register, An.

whose

address

is

in

Examples:
MOVE.B

(A0),Dl

Move the byte whose address is
in A0, into register Dl.

ADD.L

D3,(AS)

Move the contents of register D3
(32 bits) into the long word whose
address is in AS.

ADDRESS REGISTER INDIRECT WITH POST INCREMENT
Format:
(An)+

where n isa number, 8 thru 7.

The operand is pointed to by the specified address register, as
it was in Address Register Indirect; After the address is used,
the register An is incremented by 1, 2, or 4, depending on
whether the operation specifies byte, word, or long word.
Examples:
MOVE.B

D4,(A2)+

ADD.L . (A3)+,D8

Move the low byte of D4 to the
address in A2, then add 1 to A2.
Add the long word whose address
is in A3, to D0; then add 4 to Al.

Preliminary DOS Manual

CGC 7900

ADDRESS REGISTER INDIRECT WITH PREDECREMENT

Format:
-(An)

where n is a number, 0 thru 7.

The operand is pointed to by the specified address register, An.
Before the address is used, it is decremented by 1, 2, or 4,
depending on whether the operation specifies byte, word, or long
word.

Examples:
MOVE.L

D2,-(Al)

Decrement Al by 4; then move 32-bit
data from D2 to the location whose
address is in Al.

CLR.B

-(AS)

Decrement AS by 1, then clear the byte
at that address (set it to zero).

ADDRESS REGISTER INDIRECT WITH DISPLACEMENT

Format:
deAn)

where n is a number, 0 thru 7;
d is a 16-bit displacement.

The displacement d is added to the contents
This sum provides the address of the operand.
Sign-extended 16-bit number.

ot register An.
d is a used as a

Examples:
MOVE.B

D3,TABLE(A3)

Move the low byte of D3 to
the address pointed to by the
sum of TABLE plus the contents
of Al.

CMP.W

2(AB),D7

Compare the lower word (16 bits)
of D7, to the word whose address
is two plus the contents of A0.
This is the address of the first
word after (AI).

CGC 7908

Preliminary DOS Manual

Page 3-42

ADDRESS REGISTER INDIRECT WITH INDEX
Format:
d(An,Rn.W)
d(An,Rn.L)

where n is a number, 0 thru 7,
d is an 8-bit displacement.

The index register (Rn) may be any address or data register.
The low word or the entire register may be used as index,
depending on whether the suffix ·.W· or -.L- is appended to the
index register name.
If
The displacement d is used as an 8-bit sign-extended numb'er.
the low word of Rn is specified, its value is also sign-extended.
Examples:
MOVE.L

Name(Al,D4.W),DS

AND.B

D0,1(A0,D7.L)

Move 32-bit data from the
address given by: the
contents of Al, plus the
l6-bit contents of D4, plus
the 8-bit value of Name.
Data moves into DS.

Logical AND the low byte of D8,
with the byte whose address is
given by: AS plus D7 (32 bits)
plus 1. The result is placed
in this same memory address.

~GC

Preliminary DOS Manual

7909

Page 3-43

ABSOLUTE SHORT
rhe absolute address of the operand is specified. It is used as
to
a sign-extended l6-bit number, which limits this mode
addressing memory between $0000 and $7FFF, and between $FF8000
and $FFFFFF.

NOTE: If the statement ORG.L is included in the
program, this addressing mode will not be used by the
assembler. Absolute Long will be substituted (see
below).

Example:
JMP

$4B0C

Jump to address 4B9C (hex)

MOVE.L

Al,$l29

Move the 32-bit contents of A1
to address 120 (hex)

ABSOLUTE LONG
The absolute address of the operand is specified, and is used
a 32-bit number.

Example:
ADO.W

$lA2BC,D3

Add the l6-bit data from address
lA2BC to register 03, leave the
result in 03.

JMP

$890998

Jump to address 809B08 (hex)

as

Preliminary DOS Manual

CGC 79fc'"

Page 3-44

PC WITH DISPLACEMENT
Format:
*+d

where d is a 16-bit expression.

*-d
The address of the operand is given by adding the sign-extended
displacement d to the current value of the program counter.
The expression "*" has the value of the SECOND w()rd of the code
which is generated for this instruction.
Therefore, if the
instruction has a label NAME, the value of "*" is NAME+2.
Examples:
BRA

*+$18

Branch to the address 20 hex bytes
(16 words) past this instruction.

LEA

*+LABE,L-(IRC+2'> ,AS

The second
example
above
would
be
used
to
generate
position-independent code for loading the address of LABEL into
AI. It would be operationally similar to the statement
MOVEA.L 'J:,ABEL,AS

-

which would also load AS ,~4'd.~.Lh,fL,~",a.dl:!l·~ess of LABEL.
However,
the LEA sta tement above takjts_ ..f~l{~.J;'. by"tes);; and is preferred if
LABEL is within the 16-bit OIsplacemene""range required by this
addressing mode.

Preliminary DOS Manual

CGC 7909

PC WITH INDEX
Format:
*+d eRn.if)

where d is an 8-bit expression,
Rn is an address or data register.

*-d (Rn.L)
The address of the operand is given by adding the sign-extended
displacement d, to the 16 or 32-bit contents of register Rn, and
to the current value of the program counter.

Examples:
JMP

*+OFFSET(D3.L)

Jump to the address given
by OFFSET plus the 32-bit
contents of D3, plus the
current Program Counter.

MOVE.W

*+(DATA-(IPC+2»(AB.W),D4
Move a word into D4
from the address which is
beyond label DATA by an
amount contained in AB.W
(the low 16 bits of AB).

Preliminary DOS Manual

CGC 79""

Page 3-46

IMMEDIATE
Format:
', 
where  is a decimal number (the terminating
comma is required by the arg parser)
 is a single character

i

'~*

*
*
*

MOVEM.L D0-D2,-(SP)

Save what we use

MOVE.W
MOVE.B

Get first argument (decimal I)
Get second argument (char)

(Al)+,D2
(AI) ,D0

Now do something useful with the args •••
Print character  on the screen,  times.

CLR.L
PRNT
JSR
CHAR OUT EOU
SUBO.W
BNE.S

Dl
CHAR OUT
$800008

Specify Logical Output Dev "
Print the char in D0
(See Jump Table description)

Il,D2
PRNT

Decrement the count
Do until D2 = "

MOVEM.L (SP)+,D0-D2
RTS
MdleEnd EOU
DC.L
END

1PC
-1,-1

Restore what we saved

End of modules

CGC 79"1

....

Preliminary DOS Manual

Page A-14

Preliminary DOS Manual

CGC 790"

Page A-IS

PLOT MODULES
A Plot module performs a graphics function. All of the plotting
features in the 7900 firmware are written as Plot modules.
Plot
modules generally accept coordinate data as arguments, and
perform some plotting function based on this
data.
The
nlinking- procedure used for all modules means that you can
write your own Plot modules, link them in to replace existing
modules in the 7900 firmware, and implement any features you
desire.
Plot modules begin with a length descriptor (word).
This is
followed by the Plot character (control-B, decimal 2) and a
character which identifies the module.
The identifier may be
any character above ASCII R@_ (hex $40).
The next two words
specify arguments to be passed to the Plot module.
This
argument list is similar, but not identical, to the argument
list for Mode modules.
Once a Plot code sequence has been entered, execution of the
Plot module begins. The module is then repeatedly called, each
time enough arguments have been entered to satisfy its list.
The FIRST time a Plot module is entered, it may wish to perform
a different sequence of instructions to initialize itself.
A
status bit tells the module whether it is being entered for the
first time, or on subsequent calls. Also, the second word of
the argument list is used to select arguments for the first
call, and the first word selects arguments for subsequent calls:
DC.W
DC.B

ModEnd-IPC
Plot, • Z'

DC.W
DC.W

$0011
$0008

Two chars for repeated calls
Coord arg for first call

In this example, the Plot module requires a coordinate argument
when it is first executed.
After the coordinate argument is
satisfied, the module is entered. The system will, from that
point on, accept two single characters before entering the
module.
(This is the argument scheme used by Incremental
Vector.) The process of scanning for a pair of characters, and
calling the module, continues until another Plot submode is
entered or until the user turns -Plot Off.-

~ ..

Preliminary DOS Manual

CGC 7988

Page A-16

On entry to the Plot module (and other modules), certain
registers are set up for convenience.
Applicable to this
discussion is D7, which contains window status.
The wSubmode w
bit of D7 (bit 17) is set when a Plot module is first entered,
to indicate that -this Plot Submodewas just entered. w If t2l Plot
module cares about whether the submode has just been entered,. it
must check this bit and perform any necessary initialization if
the bit is' set. Then, it must clear the -Submode- bit.
If the Plot module does not make this distinction, and does not
care whether it has just been entered, then the argument list
should be duplicated in the first and second word:
DC.W
DC.B

ModEnd-IPC
Plot,'Z'

DC.W
DC.W

$SSS8
$SSS8

A coord for repeated calls
and also for the first call.

Note that Plot modules may only parse FOOR arguments
execution begins; Mode modules could have up to eight.

before

So that Plot code and Mode code arguments will not conflict,
Plot arguments are stacked on the wA3 Stack w and may be picked
up from the addresses pointed to by Al.
Remember that more than one window at a time may be in the same
Plot Submode. A Plot module should not store any local data
which could interfere with another window calling the Plot
module. Local data should be stored in the window table, or
somehow be localized to the window •

....

Preliminary DOS Manual

:GC 790S

*
*
*

Plot

A

sample Plot module.
ORG.L
DC.L

$lFSeS
'MDLE'

DC.W
DC.B
EOO

ModEnd-IPC
Plot,'Z'
2

(Plot is Control-B)

DC.W
DC.W

$eeeS
$eeSS

One coord pair normally,
Two pair the first time thru.

17
tSubmode,D7
Norm

Did we just enter the submode?
No ••• normal entry

Submode EOO
BTST
BEO.S

.

*
*
*
**
*

Norm

**
*

*

Page A-17

Submode was just entered. We can initialize ourself
in this block of. code if necessary.
BCLR
RTS

tSubmode,D7

Prepare for next entry

Come here if submode was NOT just entered.
MOVEM.L DS-D2,-(SP)
MOVE.W (A3)+,DS
MOVE. W (A3) ,D1

Save registers
Get X argument into DB
Get Y argument into D1

Now, do something with the arguments here ••••
Maybe plot a vector or something.
MOVEM.L (SP)+,DS-D2
RTS

Restore registers

....

CGC

7908

Preliminary DOS Manual

Page A-IS

ESCAPE AND USER MODULES
Escape and User modules are identical to each
similar to the Mode modules discussed earlier.

other,

and

are

An Escape or User module begins with a length descriptor (word),
followed by the Esc ($lB hex) or User ($15 hex) character, and a
single ASCII character which identifies the
module.
The
identifier may be any character above ASCII '@' ($48 hex).
The next two words define an argument list, exactly like a Mode
module. All arguments (up to eight) are parsed by the Escape
Code Processo.r and are passed to the Escape or User module.
Arguments are found on the Al stack (pointed to by Al).
This
does not conflict with the stack of Mode arguments because
Escape and User codes are processed by a different routine than
Mode codes.
Remember that Escape and User codes have
the 7900 code processing scheme. Escape
not specific to a window, so they should
functions affecting the entire machine.

identical priority in
and User modules are
be used to implement

Preliminary DOS Manual

CGC 7999

**
*

*

Page A-l9

A sample Escape code module to play with the
lights on the keyboard. This could also have
been written as a User module.

*

Esc

Keybrd

ORG.L
DC.L

$lF000
'MDLE'

Identify a module is here

DC.W
DC.B
EQU

MdleEnd-IPC
Esc,'X'
$lB

Length descriptor
Escape X is our sequence

DC.W
DC.W

$0000
$0004

We want one decimal I

MOVE.W
EQU

(Al),Keybrd
$FF8080

Send it to the keyboard
(Keyboard address)

RTS
MdleEnd EQU
DC.L
END

I PC--

-1,-1

CGC 7900

Preliminary DOS Manual

Page A-2S

REGISTER SETUP FOR MODULES
When a module is executed, several registers are pre-loaded for
convenience. The following table defines what each register is
used for, when each type of module is entered.

Module

Register Usage

B (boot)

No registers pre-loaded.

I (input)

No registers pre-loaded.

o

No registers pre-loaded.

(output)

Mode, Plot

Am: Points to base of Window Table for
the window which called the module
(see Window Table description).
A1: Points to Mode arguments
(parsed
before module execution begins).
A3: Points to Plot arguments
(parsed
before module. execution begins).
D7: Contains window status for the window
which called the module (see Window
Table description).

Escape, User

Am: Points to base of the Window Table
for window A (the Master Window).
A1: Points to arguments (parsed before
module execution begins).
D7: Contains window status for
and Escape code status.

window A

Preliminary DOS Manual

CGC 7900

Page A-2l

WINDOW TABLE
512 bytes of data are

allocated as a Window Table for each
active window. These bytes hold the current status of the
window, including such items as color, blink, scale, window
limits, and most other window attributes. Window attributes are
usually set by Mode code sequences, and Mode modules will often
want to alter items in a Window Table.
The following chart lists the location of each item in the
window table, by giving an offset into the table where each item
may be found. An item can be altered by a module by using the
listed offset as a displacement from (AI), since
AI
is
pre-loaded with the base of the Window Table. For example,
FrgCol

EQO

$8E

MOVE.W FrgCol(AB),DI

Offset in table
for Foreground color
Get color into D0

In this table, entries are marked with -.8-, -.W-, or
indicate the appropriate data size (where possible).
$11
$94
$98
$9C
$19
$14

.L
.L
.L

.L
.L

.L

$18 .L
$lC .L

TVALUE:

Arglst:
Parglst:
STATUS:
AArgstk:
Atgdsp:
Aprgstk:
Prgdsp:

Temporary storage area (reserved)
Mode argument list
Plot argument list
copy of D7 status long word
pointer to Mode argument stack
Mode dispatch address
pointer to Plot argument stack
Plot dispatch address (submode)

Window variables are stored beginning here
and occupy one word each.
$21 .W
$22 .W

•
•

$5C .W
$5E .W

-.L-, to

Window Variable A
Window Variable B
Window Variable _
Window Variable '

Preliminary DOS Manual

CGC 7988

Page A-22

The following items are also Window Variables but
are used for system data as well.
AcursX:
AcursY:
CursX:
CursY:
AwindX8:
AwindYI:
AwindX1:
AwindY1:
WindXI
WindY8
WindX1
WindYl
CharXZ
CharYZ
CharDX
CharDY
CharXM
CharYM
XVmin:
YVmin:
Tabcol:
Vecwid:
BkgCo1:
FrgCo1:
P1aneE:
CursCol:
01dX:
OldY:
Xscl:
YScl:
Charadr:
Endbuf:
Plotdot:
Plotvect:

$"68 .W

$62 .W
$64 .w
$66 .W
$68 .W
$6A .W

$6C .W
$68 .W
$78 .W
$72 .W
$74 .W
$76 .W
$78 .W

$7A .W
$7C .W
$7E .W
·$88 .W
$82 .W

$84 .W
$86 .W
$88 .W
$8A .W

$8C .W
$8E .W
$98 .W

$92 .W
$94 .W
$96 .W
$98 .W

$9A .W
$9C .L

$A8 .L
$A4 .L
$A8 .L

Overlay cursor X position
Overlay cursor Y position
Bitmap cursor X position
B~tmap cursor Y position
Overlay window upper left corner X
Overlay window upper left corner Y
Overlay window lower right corner X
Overlay window lower right corner Y
Bitmap window upper left corner X
Bitmap window upper left corner Y
Bitmap window lower right corner X
Bitmap window lower right corner Y
Character X raster size
Character Y raster size
Character delta X after write
Character delta Y after write
Character X multiplier
Character Y multiplier
Virtual X minimum value
Virtual Y minimum value
Tab stop spacing
Vector width
Background color
Foreground color
Planes enabled
Cursor color (not used, reserved)
Rubber band X position
Rubber band Y position
Virtual X Scale value
Virtual Y Scale value
Character set base address
End of arguments for virtual coordinate
Dispatch address for dot plotting
Dispatch address for vectors

The following five items are u.sed for
raster processor operations in the window.
$AC .W
$AE .W
$B8 .W

$B2 .W
$B4 .W

WXsrc:
WYsrc:
WDXsrc:
WDYsrc:
Wctrl:

X source raster operating point
Y source raster operating point
Delta X for source raster
Delta Y for source raster
Control bytes for rasters

:GC

Preliminary DOS Manual

7999

$B6-$F5
Curstg:
$F6-$135 Argstk:
$136-$lB5 Pargstk:

Page A-23

32 words for cursor pixel storage
Argument stack for Mode args (32 words)
Argument stack for Plot args (64 words)

The following four bytes contain the current
Overlay color, blink and transparency attributes.
$lB6
$lB7
$lB8
$lB9
$lBA-$lFF

AentSt:
AentBCc
AentFC:
AentCh:

Transparency
Background color
Foreground color
ASCII character portion
Reserved for future expansion

....

CGC 7908

Preliminary DOS Manual

Page A-24 .

WINDOW STATUS AND ESCAPE CODE STATUS
As shown before, register D7 is
pre-loaded
with
status
information when certain types of modules are executed.
The
bits in D7 are defined as follows:
Meaning

Bit
8
1
2
3
4
5

6
7
8

9
18
11

12
15

16

17.
18
19

20
21
23

24
25
26
27
28

29
38

31

modeF:
plotF:
Moredat::
Negnum:
visctrl:
Pltmode:
Overlay:
Curson:
FilIon:
Blinkon:
Rollon:
OvrStrk:
Binmode:
Rubron:
Patton:
Submode:
Cursin:
BinTwo:
VScale:
A7on:
Local:
Full:
Escflg:
Osrflg:
Create:
LitP0 :
LitPl:
Literal:
Escdone:

Other bits are reserved.

Mode flag used by window processor
Plot flag used by window processor
Control bit used by argument scanners
Control bit used by argument scanners
SET when visible ctrls are on
SET when in a plot submode (not alpha)
SET when Overlay on (not Bitmap)
SET when cursor is on
SET when fill is on
SET when blink is on
SET when roll is on
SET when overstrike is on
SET when binary mode is on
SET when rubber band is on
SET when patterns are on
SET when plot submode just entered
SET when Bitmap cursor in screen RAM
Flag for binary coordinate parser
SET when scaling is on
SET when A7 character set active
SET in LOCAL mode
SET in FULL duplex
Escape code processor flag.
Escape code processor flag
SET if Create is on
Escape code processor flag
Escape code processor flag
SET if Literal Create is on
Escape code processor flag

CGC

Preliminary DOS Manual

79~1/J

Page A-25

JUMP TABLES
This section desribes the utilities available in CGC 7901/J PROM
firmware. Each of these· routines may be accessed through a
subroutine call (JSR) to the appropriate address. Note that BSR
would not work because in general, jump tables are located more
than a l6-bit displacement from your program in RAM.
Registers used in each routine are defined in this section.
Unless noted, the routine only alters registers as necessary to
return values to the caller. The notation "Dl.W" means that the
low word (16 bits) of 01 are used by the routine, DI/J.B means the
low byte of 00, and so on.

Name:
CHAROUT
Address: $801/J1/J1/J8
Entry:

D0.B = character to pass to logical device
Dl.W = logical device number (I/J to 4 are defined)

CHAROUT is the system character-out routine.
It passes a
character to a logical output device.
The system's device
assignment structure will then pass the character on to a
physical device, if possible.
Logical output device I/J is
normally used to put characters on the screen, and device 1 is
normally connected to the serial port. If the character 'is part
of a Mode or Plot code sequence, it will be processed when it
reaches a Window (physical device). Escape and User codes are
NOT processed by CHAROUT, but are treated as normal-characters.
To process Escape and User codes, see CTRLOUT, CTRLIN and
ESCPROC below.

Name:
CHAR IN
Address: $801/J1/J1/JC
Entry:

Dl.W = logical device number to read from

Exit:

Zero flag SET if no character was available
Zero flag CLEAR and character in DI/J.B if available

CBARIN is the system character-in routine. It reads a . character
from a logical input device.
Reading from device 8 will
normally get a character from the keyboard (If available),
device 1 will normally be the serial port.

Page A-26

Preliminary DOS Manual

CGC 79""

TO wait for a character
condition:
L.oop

JSR

8EQ.S

from

CHARIN,

CHAR IN
Loop

use

a

loop on

the

EQ

Get a character, if any
No character yet

Escape and Oser codes are not processed by CHARIN, but are
treated as· normal characters. See CTRLOOT, CTRLIN and ESCPROC
below.
Name:
CTRLOOT
Address: $899911
Entry:

01.8 = character to pass to logical device
Dl.W • logical device number
Zero flag must NOT be set
Gt-{hf

Xl

YI
X2

Each item in this
table is one word.

Y2

------------1
X3
Y3
•
•
•

Xn
Yn
Endbuf(A0) ->

EE
EE

Pairs of words before and after the
above) ate used as scratch areas by
should allow room for them.

list (marked BB
POLYG, and your

and EE
program

CGC 790"

Preliminary DOS Manual

Page A-36

The following code might be used to call POLYG:
$136
$A"

Pargstk EOO
Endbuf EOO
LEA
MOVE.L
MOVE.W
MOVE.W
MOVE.W
MOVE.W

Offsets in W table

Pargstk(Ae),Al
AJ,-(SP)
Xl, (A3) +
YI, (A3) +
X2,(Al) +
Y2, (Al) +

Point to arg stack
Save pointer
Load coordinates
onto AJ stack

•

•
•
MOVE.W Xn, (A3) +
MOVE.W Yn, (Al) +
MOVE.L A3 , Endbuf (AO)
MOVE.L (SP)+,AJ
JSR

....

POLYG

Put last values
Set up end of list
Retrieve pointer to
start of list
Do polygon

Preliminary DOS Manual

:GC 7geB

Page A-37

DOS JUMP TABLES
~ame:

\ddress:

DOS

$8~C~B8

rhis is the main entry point to DOS.
It requests
password and begins accepting DOS commands.

the

user's

Name:
EXDOS
Address: $8~C0IC
Entry:

Al.L = pointer to command line

Exit:

Al.L = pointer to next (unprocessed) character in line
De.B = error code (if any), or zero if no error

EXDOS attempts to execute a transient.
The name of
the
transient should be pointed to (on the command line) by Al.
EXDOS calls GETNAM to parse the transient name, OPEN to locate
the file on disk, and LOAD to load the file into memory.
If
successful, execution begins at the transient's start address.
The TRANSIENT is responsible for returning Al and DB as required
above.

Name:
OPEN
Address: $8~CIII
Entry:

AI.L

Exit:

DI.B

= pointer to
= error code

OFT in use
(if any), or zero if no error

OPEN looks up a file on a disk. Before calling OPEN, the OFT
(Oser File Table) should contain the complete filename: primary,
secondary, password, and drive. (The OFT is an area of RAM
which defines the current status of a file, and includes all of
the file's vital statistics. OFT's are discussed later.) See
GETNAM for a way to parse the filename.
If successful, OPEN
will add the following information to the OFT: START, LENGTH,
ACCESS, STATUS, BPNTER, BLNGTH, SLOT.
If unsuccessful, DI.B
holds the error code.

Preliminary DOS Manual

CGC 7908

Page A-38

Name:
CLOSE
Address: $80C014
Entry:

A0.L - pointer to UFT in use

Exit:

08.B • error code (if any), or zero if no error

CLOSE enters a new file into the disk directory.
The UFT must
be completely built before callin9 CLOSE. CLOSE is only used on
files which have been created by CREATE, not on existing files
which have been OPENed. If the file name specified in the UFT
already exists, the old file
by
that
name
is
killed
automatically.

Name:
CREATE
Address: $8fiJC018
Entry:

AB.L

Exit:

OB.B

= pointer to
= error code

UFT to be used
(if any), or zero if no error

CREATE prepares the largest available free space on the disk for
writing. Before calling CREATE, the UFT should contain the
complete filename: primary, secondary, password, and
drive
number. CREATE will add SLOT, START, LENGTH, ORIGIN, ACCESS,
BPNTER and BLNGTH.
These items will reflect the
largest
currently available disk space.

Name:
LOAD
Address: $80C02B
Entry:

AB.L • pointer to OFT in use

Exit:

00.B· error code (if any), or zero if no error

LOAD reads an executable file into memory. The file must be in
load module form, as a .SYS file..
If the file is loaded
successfully, RAM location GOAD DR ($11B4) will contain the
file's normal execution address. LOAD returns to the caller,
who may then jump to the address in GOADDR if desired.

Preliminary DOS Manual

CGC 799"

Page A-39

Name:
RWBYTE
Address: $80C024

= pointer

Entry:

A".L

to UFT in use

Exit:

D".B = error code (if any), or zero if no error

RWBYTE is the main disk read/write routine.
The UFT must
contain proper values in BUFFP, MBYTES, DRIVE, CONTROL, BPNTER,
BLNGTH, and STATUS. BUFFP is the memory address to/from which
data will be moved. MBYTES is the number of bytes. If MBYTES <
128, then data may be transferred to/from an odd memory address.
If MBYTES >= 128, data must be transferred to/from
even
addresses only.
On exit, BUFFP points past the memory location where the last
transfer took place. MBYTES will be zero if all requested bytes
were transferred, else it will be the number of bytes NOT
transferred (due to error). The EOF bit of CONTROL will be set
appropriately. BPNTER and BLNGTH will be updated according to
the current state of the file.
Name:
GETNAM
Address: $8"C"64
Entry:

A".L = pointer to UFT to use
Al.L = pointer to input buffer (command line)
A2.L = pointer to default filename

Exit:

D".B = error code (if any), or zero if no error
Dl.B = last character processed
Al.L = pointer to first unprocessed character

GETNAM parses the input buffer and extracts a file name.
All
parts of the file name are loaded into the UFT. A string of 11
characters to be used as a default name (if no name was entered)
must be pointed to by A2.
If no password was entered, the
current user password is copied into the OFT.
If no drive
number was entered, the current drive number is copied into the
OFT.
GETNAM returns Di.B with the delimiter it found after the file
name. This may be a colon, in which case you must flag to DOS
that another command exists on the input line. It may also be a
semicolon, used to delimit an option field. Al should be saved
for return to DOS, or used as a pointer to further arguments on
the command line (if your program expects any).

Page A-48

Preliminary DOS Manual

CGC 7981
Name:
PRTMSG
Address: $88C184
Entry:

AI.L • pointer to ASCII string (terminated by zero)

PRTMSG transmits an ASCII string to Logical Output Device zero,
which will. normally display it on the screen.
PRTMSG goes
through CTRLOUT to allow Escape and User code processing.

Name:
PRTBEX
Address: $88C894
Entry:

D8.L • data (hex long word)
Dl.L • number of hex digits to print (1 to 8)

PRTHEX prints a hex number to Logical Output Device zero
(normally the screen). The number is preceded by a dollar sign
($). 01 specifies the number of hex digits to print, and these
are taken from the least significant digits of 08. (If Dl = 2,
then the low byte of D8 is printed.) The hex number is
left-justified, and padded on the right
with
spaces
if
necessary, to fill out the number of characters specified by 01.
This is the format of hex numbers printed in the disk directory.

Name:
GETCLK
Address: $88C898

....

Entry:

No setup required

Exit:

D8.L • packed time and date information from clock

GETCLK reads the Real Time Clock and encodes
information into a long word.
If tbeclock
installed, the long word contains zero •

time and date
option is not

Preliminary DOS Manual

:GC 7900

lame:
~ddress:

Page A-4l

CLKBCD
$80C0A0

= packed time and date in
= pointer to 19-character

~ntry:

D0.L
A0.L

GETCLK format
buffer

Exit:

Buffer is loaded with ASCII time and date

CLKBCD unpacks the time and date information produced by GETCLK.
The buffer pointed to by A0 will be loaded with month, day,
year, hour, and minute information in ASCII form.
A zero byte
is appended to the ASCII text so that it can be printed by
PRTMSG. If D0 contained zero on entry to CLKBCD, the buffer·
will be loaded with 18 spaces and a zero.

Name:
GETARG
Address: $80C0A8

= pointer

Entry:

A1.L

to input· 'buffer

Exit:

Al.L = pointer to character past delimiter
Dl.L = hex argument returned
D0.B = zero if no error, non-zero if error

GETARG parses a hex number from an input buffer.
The value of
the argument is returned in Dl. D0 is non-zero if a non-hex
character was detected before the delimiter was reached.
If 00
is zero, no error was detected.
Al is advanced past the
argument.

Name:
DOSERR
Address: $80C9BC
Entry:

A0.L = pointer to OFT of the file which caused an error
D9.B = error code

DOSERR prints a DOS error message.
The drive number of the
offending file is printed also. Error codes available in DOSERR
are listed in the Appendix. Note that DOS automatically prints
error messages if your transient returns to DOS with D9.B
non-zero.

Preliminary DOS Manual

CGC 799"

Page A-42

INLINE CALLING SEQUENCE
Name:
INLINE
Address: $89A09C
Entry:

Al.L • pointer to input buffer to be used
Dl.W • Logical Input Device number to read from
D7.8 • control bits (see below)

Exit:·

Zero flag SET if the user hit DELETE
Zero flag CLEAR if the user hit RETURN
"--,

..........

INLINE is the 7999's general-purpose input routine, used by DOS,
the Monitor, and Thaw. It reads a line of up to 83 characters
from the user, allowing character editing, Recall Last Line,
etc. Bits in D7 control INLINE as follows:
Bit

Meaning if SET

3

Echo the input line to the screen after
RETURN is pressed (in expanded form, Modes
and tabs executed normally).

2

Process Escape and User codes as they are
entered.

1

Use wA7 w character set for control-characters
displayed in compressed form.
Do not display the characters as they are
entered (you can't see what you type).

DOS uses D7 equal to $0E, Dl equal to zero, and Al pointing to
the DOS input buffer in low RAM. The input buffer supplied to
INLINE should be at least 85 characters long.
The end of the
user's input line is indicated by a Return character in the
buffer.

GC 790"

Preliminary DOS Manual

Page A-43

CMOS MEMORY ALLOCATION
~096 .bytes of CMOS or static memory· are
installed on the 790"
:PU card.
This memory is used
to
store
Function
Key
iefinitions, information for buffer sizes, and other important
;ystem pointers. The CMOS memory is optional, and comes with a
)ettery-backed supply so that user-defined parameters will be
naintained while the system is turned off.
This concept is
Jescribed in detail in the 7900 User's Manual description of the
"Thaw" command. If your system does not contain the CMOS option,
you will have static RAM installed at these addresses, but the
data in this RAM will still correspond to the following table.

This section describes the allocation of CMOS memory in the
current version of firmware, TERMEM 1.1. Allocation may change
slightly or greatly in future releases.
All CMOS is reserved
for system use, and any user programs which occupy CMOS do so at
the risk of interfering with future system programs.
The CMOS entries which determine buffer sizes should not be
altered except through the Thaw command.
If these entries do
not agree with actual RAM allocation at all times, the system
can crash.
Addresses $E40000 through $E4"l"" are also used by hardware
registers in the 7900 system. Accessing these addresses affects
CMOS and the hardware as well.
Where appropriate in the following tables, each entry is marked
with ".B", ".W", or ".L", to indicate the data size of the entry.
Address
$E40000
.W
$E4""02
.W
$E4""04
.W
$E4""06
.B
$E40007
.B
$E40008-$E400"9
$E4"00A-$E4000F
.W
$E4"0l0
$E4"0l2
.W
$E400l4
.W
$E400l6
.W
$E4"0l8
.W
$E40"lA
.W
$E4001C-$E4001F
$E40020-$E4003E

Use
Bitmap roll counter
X pan register
Y pan register
X zoom register
Y zoom register
(Reserved)
Raster processor registers
Blink select register
Plane select register
Plane video switch register
Color status foregrou~d register
Color status background register
Overlay roll counter
(Reserved)
Raster processor registers

Preliminary DOS Manual

CGC 7900
$E40040-$E4010B
$E4010C
.L
$E40110-$E40113
$E40114
$E40116
$E40118
$E40119
$E4811A
$E4011C
$E4811E
$E48128
$E40122
$E48124
$E40126
$E48128
$E4012A

.w
.W

~B

.W

.W
.W
.W

.W
.W
.W

.W
.L

$E4812E
.L
$E48132
.L
$E48136-$E48141
$E48142
.L
$E48146
.L
$E4814A
.L
$E4814E-$E4815D
$E4815E
.L
$E48162
.L
$E40166-$E48169
.L
$E4816A
$E4016E
.L
$E40172-$E40179
$E4017A-$E4817B
$E4817C-$E481C7
$E401C8-$E48213
$E40214-$E4021D
.L
$E4021E

Page A-44

(Reserved)
CMOS verifier long word
(Reserved)
Size of DOS Transient Program Area
Size of DOS Buffer
Number of active windows
(Reserved)
Size of keyboard buffer
Size of Function Key stack (nesting)
Size of RS-232 input buffer
Size of RS-232 output buffer
Size of RS-449 input buffer
Size of RS-449 output buffer
Size of Escape code argument stack
Size of system stack
Highest RAM address used by system
Pointer to INtINE recall buffer
Recall bu.ffer size
Pointers for INtINE
Pointer to start of Function Key buffer
Pointer to end of Function Key buffer
Pointer to Case Table
(Reserved)
Address of default program (executed by Boot)
Address to search for RAM modules
TERMEM status flags
Address of Bitmap plot cursor descriptor
Address of Bitmap alpha cursor descriptor
. (Reserved)
INtINE Recall flags
Default Boot string
Default Reset string
Bost EOt sequence
Address of vector-drawn character font

$E40222
.B
$E40223-$E48224
$E48225
.B
$E48226-$E40229
$E4022A
.B
$E4822B-$E4822C
$E4822D
.B
$E4822E-$E48231

RS-232 mode command
(Reserved)
RS-232 handshake flags
(Reserved)
RS-449 mode command
(Reserved)
RS-449 handshake flags
(Reserved)

$E48232-$E487FP
$E40808-$E488FP
$E40900-$E40BFP
$E40C08-$E40CFF
$E40D00-$E40PFP

(Reserved)
Case Table
Function Key buffer
INLINB Recall buffer
(Reserved)

CGC 7900

Preliminary DOS Manual

Page A-45

LOW RAM ALLOCATION
The area of RAM between addresses $400 and $FFF is used by the
7900 system for pointers and miscellaneous constants.
The area
between $1000 and $lC3B is used for DOS tables and pointers.
As
mentioned earlier, areas marked "Reserved- should be left alone,or risk incompatibility with future releases of software.
Use

Address
$400-$463
$464-$495
$496-$4E5
$4E6-$509
$50A-$69B
$69C-$BFF
$C00 .L
$C04 .L
$C08 .L
$C0C .W
$C0E .L
$C12 .W
$C14 .W
$C16 .W
$C18-$ClB
$ClC .L
$C20 .L
$C24 .L
$C28 .L
$C2C .L
$C30.L
$C34 .L
$C38 .L
$C3C .L
$C40 .L
$C44 .L
$C48 .L
$C4C .L
$C5e .L
$C54 .L
$C58-$C5D
$C5E-$C6l
$C62 .W
$C64 .W
$C66 .W
.$C68-$C7F
$C8e .L
$C84 .L
$C88-$C8D
$CSE .L

-

Monitor input line
Monitor flags and breakpoint storage
Monitor pseudo-register storage
Monitor register display formats
Monitor stack
(Reserved)
Pointer to base of TERMEM dispatch tables
Pointer to Keyboard buffer ·start
Keyboard input pointer
Keyboard buffer character count
Pointer to Keyboard buffer end
Joystick X center offset
Joystick Y center offset
Joystick Z center offset
Light pen argument list
Function Key stack pointer
Pointer to Function Key buffer
Pointer to Function Key stack
Pointer to RS-232 input buffer
Pointer to RS-232 output buffer
Pointer to RS-449 input buffer
Pointer to RS-449 output buffer
Pointer to Esc argument stack
Pointer to DOS buffer
Pointer to window table base
Pointer to top (start) of stack
Pointer to bottom (end) of stack
Pointer to start of Create Buffer
Pointer to end of Create Buffer space
Pointer to DOS transient area
TERMEM storage for keyboard light data
TERMEM storage for HVS calculations
Active image planes in system
Copy ot interrupt mask register
Copy of baud rate generator data
Escape code processor storage area
Pointer to current character in Create Buffer
Pointer to end of Create Buffer data (EOF+l)
Joystick data storage area
Warmstart vector (for USER W)

Preliminary DOS Manual

CGC 798"
$C92-$C99
·$C9A-$CAl
$CA2-$CA9
$CAA-$CB1
$CB2-$FFI'

Page A-46

RS232 input ring buffer pointers
RS232 output ring buffer pointers
RS449 input ring buffer pointers
RS449 output ring buffer pointers
(Reserved)

DOS memory allocation begins here ••••
$1888-$1889

DOS command block for disk controller

$188A-$183F

Default DOS OFT (details below)

$1848-$113F
$1148-$1143
$1144-$118B
$118C-$11B3

Directory buffer space
Command block variable space
DOS input line buffer
DOS variables and pointers

$11B4

GOADDR: Start address for executable files

.L

$11B8-$11C3

DOS pointers

$llC4
$llCS
$11C6

REVN:
Revision number of file (not used)
DRIVEN: Drive from which last transient came
OSERN: Password of current user (** = public)

.B
.B
.W

$11C8-$11CD

DOS variables

$llCE
$llD"

FLSTAT: File status used by CLOSE
SLASH8: Slash/8 mode flag

.W
.W

$11D2-$11E1

Disk controller variables

$11E2-$1217

TOFT1:

$1218-$1243

DOS variables

$1244-$1279

TOFT2:

$127A-$1389

DOS variables

$l38A-$13FI'

Reserved for DOS expansion

Transient OFT II

Transient UFT 12

Page

Preliminary DOS Manual

CGC 79fiJS

A-47

THE USER FILE TABLE
DOS maintains a User File Table (UFT) in memory for each file
currently being accessed.
The UFT contains the file name,
password, directory location, size, and various pointers which
uniquely identify that file. Whenever DOS reads from or writes
to a file, the UFT is updated to show the current file status.
The OFT must remain intact as long as a file is in use, or until
a new file is closed.
Each UFT occupies 54 bytes. DOS has three UFTs allocated in
RAM, and your program may use these areas to built UFTs, or
may use other RAM.

low
you

Each item in the OFT is defined below.
If A0 points to
start of a UFT, the item of interest may be accessed with
wIndirect with Displacement- addressing mode, as OFFSET (A0) •

the
the

Offset in OFT
$S0 .W
$02

.L

Description
SLOT:

Location of a file in the
directory.

disk

BUFFP: Memory address to/from which the
data transfer will take place on
the next read or write.

$S6 .L

MBYTES: Number of bytes to transfer
next read or write.

$fiJA .W

CONTRL: Defines the next operation to
be performed. In this word,
Bit
9
8
7
6

$SC .B

on

Meaning
l . End of file
I-Read, S-Write
I . Enable retry
l . Enable ECC

DRIVE:

Logical unit number of disk
drive:
S and I are floppy
disks, 2 is the hard disk.

ERROR:

Error code of last operation.

Page A-48

Preliminary DOS Manual·

CGC 798.
$8E .L

BPNTER: Pointer
file.

$12 .L

BLNGTB: Current fength of file (goes to
zero as file is read in).

$16-$lD

PNAME:

8-character primary filename.

$lE-$28

SRAME:

3-character secondary filename.

$21

REV:

File revision number
in DOS 1.4).

$22-$23

PSWRD:

2-character password.
Public
files are given password

$24

START:

Starting address
disk (bytes).

.L

to

current

byte

in

(not used

-**-.

of

file

on

$28 .L

LENGTH: Length of file on disk (bytes).

$2C .L

ORIGIN: File origin time/date.

$3 •• L

ACCESS: Time/date of last access.

$34 .w

STATUS: File attributes as follows •••
Bit
15
8
7
6
4
3
1

•

Meaning if SET
Blind file
Active slot
Write-protected
Delete-protected
Free (deleted)
Execute-only
Odd length
Killed

CGC 7999

Preliminary DOS Manual

Page A-49

WRITING TRANSIENTS
This section describes the procedure
program executable under DOS.

for

writing

a

transient

A transient must be located in an appropriate area of RAM,
usually the DOS Transient Program Area. This begins at address
$lC3C (hex). The length of this area is variable depending on
your requirements, but will normally be at least 16K bytes.
ORG.L

$lC3C

Any RAM used by a transient should be in this same area of
memory, or in the DOS Buffer which immediately follows it.
RAM
allocations are defined by pointers in system RAM and in CMOS,
described earlier. Your transient should be careful not to
exceed these allocations or the system may become confused.
When a transient is executed, DOS loads it at whatever address
it was assembled (DOS does not check whether this is a legal
address!). DOS then begins execution at the start address' you
defined in your END statement.
On entry to a transient, Al
points to the first unused character in the command line.
If your transient expects to pick up an argument from the
command line, such as a file name, Al will be pointing to that
SINGLE
argument.
Note: DOS will only advance Al past a
delimiter. If the user typed two spaces, commas, etc., Al could
be pointing to a delimiter.
If the last delimiter found by your program was a colon, assume
that another command follows on the command line, and flag this
before returning to DOS. This is done by setting Dl.B non-zero,
and pointing Al to the first character of the command following
the colon.
Note that most DOS argument parsing
routines
automatically bump Al to the next character after gathering
arguments.
Your transient now has control of the system.
Using routines
provided in the jump t'ables, your transient can. pick
up
arguments from the command line, open and close files, and
control the entire 7999 system. (See AppendixD in the 7999
, Oser's Manual for information on Traps.)

CGC

7~S8

Preliminary DOS Manual

Page A-58

Before returning to DOS, your transient must set DS.B zero if no
errors occurred. If you want DOS to report an error, put the
error number in DS.B and DOS will display the error message for
you. If an error is reported, DOS will not attempt to process
any further commands which were entered on the same command line.
If no errors were reported, and you return to DOS with Dl.B
non-zero, DOS assumes another command is waiting on the input
line to be processed.
Al should be pointing to the first
character of the next command.
Your transient will have to
determine whether a colon existed on the command line, possibly
by backing up Al to look for it. (Some DOS routines, such as
GETNAM, assist in this process by returning the delimiter
character to you).

Preliminary DOS Manual

DGe 7900

Page A-51

Summary of registers used by DOS transients:
On entry to a transient:
Al.L

points to the first unused character in the
command line.

On exit from a transient:
DO.B

must equal zero if no error occurred. If DS.B
equals zero and Dl.B is non-zero, then DOS will
attempt to process another command from the
command line. Al.L must point to the proper
character in the command line.

DO.B

must not equal zero if an error occurred. If
DS.B is non-zero, DOS assumes it is an error
number and will print the corresponding error
message. In this case, Dl and Al are not used,
but AS.L must point to the OFT of the file
which caused the error (so DOS can report the
offending drive number).

AB.L

is required if DS.B is non-zero (see above).

Dl.B

is required if DS.B is zero and another command
follows on the command line (see above).

Al.L

is required if DS.B is zero and another command
follows on the command line (see above).

Preliminary DOS Manual

CGC 799.

Page A-52

*****************************************************************

*

**

*
*
**
**
*
*
*

Sample transient: READ
Command format: READ 
This transient demonstrates:
Parsing
Opening
Reading
Exiting

a file name as a command line argument
a file
data from the file
from a transient, returning properly to DOS

*
*
*
*****************************************************************
**
*
*

DOS Equates

GETNAM
RWBYTE
OPEN
PRTMSG

*
*
*

....

EQU
EQU
EQU
EQU

Get file name from input line
Read/Write bytes to disk
Open existing disk file
Print ASCII string

DOS UFT Equates

*
TUFT1
U .
SLOT
BUFFP
MaYTES
CONTRL
DRIVE
ERROR
BPNTR
BLNGTH
PNAME
SNAME

EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
EQU
REV
PSWRD
EQU
START
EQU
LENGTH EQU
ORIGIN EQU
ACCESS EQU
STATUS EQU

*

$81CI64
$81C924
$81CI19
$81CI84

$11E2

•

U
SLOT+2
BUFFP+4
MBYTES+4
CONTRL+2
DRIVE+1
ERROR+1
BPNTR+4
BLNGTH+4
PNAME+8
SNAME+3
REV+1
PSWRD+2
START+4
LENGTH+4
ORIGIN+4
ACCESS+4

OFT .1 for transients
Base of UFT
Logical file number
Memory pointer for transfer
• of bytes to transfer
various flags
Drive • (LUN)
Error I of last operation
Current pointer to file on disk
Current file length
Primary file name
Secondary file name
Revision level (not used)
File password
Points to file start on disk
Length of file on disk
Time/Date of file origin
Time/Date of last access
File status

Preliminary DOS Manual

CGC

7900 .

**

TERMEM Equates

*

CHAROUT
CHARIN
CTRLIN
CTRLOUT
DOSBUFP
DOSBUFZ

EOU
EOU
EOU
EOU
EOU
EOU

$800008
$80000C
$800014
$800010
$C3C
$E40ll6

Page A-53

Character-out
Character-in
Character-in with Esc processing
Character-out with Esc proc
Pointer to DOS buffer
Size of DOS buffer

*

**
*
CR

ASCII Equates
EOU
EQU
EOU
EOU

LF
DEL
XOFF

13
10
$7F
$13

Carriage return
Line feed
Delete
X-off (Control-S)

*
******************************************************************
*

*
*

The transient begins execution here.

READ

*
**
*
*
*
*
*

ORG.L
LLEN

$lC3C
132

We run in DOS transient area
Printer is 132 columns wide

EOU
MOVE.L
MOVE.L
JSR
MOVE.L
TST.B
BNE

IPC
ITUFT1,Ae
IDefName,A2
GETNAM
Al ,SaveAl
DO
READerr

Point to
Point to
Get file
Save cmd

CMPI.B
SEQ

1':',01
Another

Was command delimiter a colon?
If YES, another command follows.

OFT to use
default name: '*.SRCI
name into UFT.
line pointer for DOS

GETNAM found an error.

The UFT now contains a filename, parsed by GETNAM. (If
no filename was entered, the default filename remains
in the UFT, *.SRC)
JSR
TST.B
BNE

OPEN
De
READerr

Attempt to open .the file.
OPEN found an error.

**

OPEN bas now provided the UFT with details of the file
length and disk location.

* s~ch as its
*
*READl MOVE.L
BEQ.S

D4.L • file length remaining
If zero, file is empty now.

BLNGTB-U(A"),D4
READex

MOVE.L DOSBUFP,BUFFP-U(AS)
CLR.L
D5
MOVE.W DOSBUFZ,D5 ,

**
*

Will it all fit?
Yes.
NO, so only read what WILL fit.

MOVE.L D4,MBYTES-U(AS)
BSET
.S,CONTRL-U(AS,
JSR
RWBYTE
TST.B
BNE
READerr

Read this many bytes
Say READ
Go and read bytes from disk.
Error from RWBYTE.

We have read bytes into the DOS buffer.
of bytes.
MOVE.L DOSBUFP,A2
SUBO.L '1,D4
CLR.W 01

** Display the
* 3 MOVE.B
READ

JSR
CMP.B
BNE.S
MOVEO.L
JSR

BEO.S
CMP.B
BEO
CMP.B
BNE.S

D4 is the number

Point to the data
Decrement count for DBRA below
Specify Device " for CBAROOT

bytes.
(A2)+,D"
CBAROUT
'CR,D"
READ4
'LF,DS
CBAROUT

** After printing each
*
READ4
JSR
CBARIN

*

D5.L = size of DOS buffer

CMP.L
D4,D5
BBI.S
READ2
MOVE.L D5,D4

D"

*

Put data in DOS buffer

Check if bytes left in file will fit into DOS buffer.

READ 2

**
*

Page A-54

Preliminary DOS Manual

CGC 79S"

READS
'DEL,D"
READ ex
'XOFF,D"
READS

Get a byte of data
Display it
Was it a Carriage Return?
No
Follow Return with Line Feed.
character, check if we should pause.
Check the keyboard.
No key was hit.
Did he hit DELETE?
yes •••• quit.
Did he hit Ctrl-S?
No, so ignore the key.

Preliminary DOS Manual

CGC 7900

*

*

Page A-55

Control-S was hit, so pause.

•READp
READS

JSR
BEQ.S
CMP.B
BEQ
DBRA
BRA

Wait for another key

CHAR IN
READp
IDEL,D0
READex
D4,READ3
READI

DELETE?
Yes, so quit.
Go display more data.
Go get more data from disk.

.****************************************************************

''**

Come here for normal exit from the transient.

•
READex
'*•

CLR.B

Come here to go back to DOS with error message.
the error code.,--,

• D0.B holds
•
READerr CLR.W

MOVE.W
MOVE.B
JSR
JSR
MOVE.B
MOVE.L
MOVE.W
RTS

Dl
D0,-(SP)
ILF,D0
CHAR OUT
CHAR OUT
Another,Dl
SaveAl,Al
(SP)+,D0

'.

DefName DC.B
DS.L

o

SaveAl DS.L
Another DS.B
DS.L

1

•

•
•

'*
'*
'•*

Flag NO error and fall into exit.

D0

END

4

"
READ

SRC'

Logical Device 0 for CHAR OUT
Save the error flag
Print a line feed
Or two •••
Flag if
Restore
Restore
Back to

another command existed
command line pointer
the error flag
you, DOS!

Default name for UFT (11 chars)
Align even addresses after DC.B
Place to save Al
Flag for colon on command line
Align even addresses after DS.B

Begin execution at label READ

CGC 7988

Preliminary DOS Manual

"-

..'

Page A-56

CGC 790S

Preliminary DOS Manual

Page A-57

CUSTOM CHARACTER SETS
The 7900 allows user-defined character sets to be used in the
Bitmap in place of the two character sets supplied with the
system. An entry in each Window Table (Charadr) points to the
base of the character set for that window, and the size of the
font (X by Y pixels) may also be defined for each window
individually. The character font dimensions may be up to 16 in
the X direction, and 256 in the Y direction.
~

Since the character set address for a window is stored in
Window Table, it will default back to the normal character
whenever Boot or Soft Boot is executed.
The character set for the Overlay is stored in
and is not alterable through software.

high-speed

the
set

PROM,

The following program is a module, designed to be linked into
the 7900 system software. It will install a custom character
set in any window which receives a wMode i W command.
This
program is an example ONLY.
It does not include a complete
character set definition. The data set which should accompany
this program would be too long to fit into the standard 7900
memory, unless you do one of the following: (1) change the ORG
address, which requires changing address MDLE with the Thaw
command, (2) change the height of the character set to reduce
the data required, or (3) install additional memory above
address $20000.

Preliminary DOS Manual

CGC 799"

**
*
**
**
*

Page A-58

Sample module to install a new character set.
The set is installed in a window by the command:
MODE 1
To return to the standard set, use

SOFT BOOT.

*
**
*

CGC 7999 equates •••

Mode

EQO

I

MODE.is Control-A

CharXZ
CharYZ
CharDX
CharDY
Charadr

EQO
EQO
EQO
EQO
EQO

$78
$7A
$7C
$7E
$9C

Offset in window table for X raster size
Y raster size
X intercharcter spacing (step)
Y intercharcter spacing
Address of font for this window

*
*

*

ORG.L

$IF999

*
*

This is the address called "MOLEas specified by the Thaw command.

DC.L

'MOLE'

This header must be present if
the modu.le is located in RAM.

DC.W

CharEnd-IPC

This is the length of the
module (including the
character set at end)

DC.B

Mode,'i'

We are executed when the user
types this sequence.

*

*
*

*
*
*

*

*
*
*
*

DC.W
DC.W

We require no arguments.

Execution begins here after MODE i is entered.
TERMEM preloads A9 with the base of the window table.
MOVE.W
MOVE.W
MOVE.W
MOVE.W
MOVE.L
RTS

t6,CharXZ(A9)
Load character size (X)
(Y)
tS,CharYZ(A9)
,
t6,CharXZ(A9)
Load step size (X)
tS,CharYZ (AB)
(Y)
tBASE,Charadr(AI}
Load address of .font
That's all!

CGC

Preliminary DOS Manual

79~1

Page A-59

*****************************************************************

**
**

*
**
*
*
*
*

What follows is the character font definition.
It is arranged as 128 regular characters, followed by 128 .
A7 characters. All 256 characters should be defined.
Assume the font is set in a field X by Y. (Default is
X = 6 and Y = 8.) Then each character requires 8 words
of data, one for each Y scan: and 6 bits of each word
are used. The active 6 bits are left-justified in the
16-bit word.

*

*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
**

*

*
*
*
*
*
*
*
*
*
*
*

Example: the character "A W
bit

•

111111

Hex value

54321~98765432l1

1

2

•

Word
(one per Y scan)

3
4
5

6
7
8

.xxx .........••.
X••• X•••••••••••
X ••• X •••••••••••

$7111
$88~1

XXXXX •••••••••••
X••• X•••••••••••

$8811
$F811
$881S

X••• X•••••••••••
••••••••••••••••

$881S
$IIIS

x ... x ........•..

$88~S

The X by Y field must include any.necessary
spacing between characters or between lines.
Memory requirements:
This module will require 256 * Y words, plus 23 words of
overhead for the preceding code. This much memory must
exist between address "MOLE" and the physical end of memory.
If necessary, use Thaw to alter the address of "MOLE" (be
sure to put it where nothing will stomp on itl)

Preliminary DOS Manual

CGC 7908

*
**
*
*
*
*

Page A-68

This 5cale Factor will left-justify a 6-bit number in a
16-bit field, by shifting 18 bits. All of the numbers in
this database are 6-bit for convenience, and S justifies
them properly.
EQO

S

1824

*
*
EQO
IPC
BASE
This is where it all begins.
**
This is the regular character set.
* DC.W
$24*S,$34*S,$3C*S,$2C*S,$24*S,$04*S,$04*5,$07*S
*
*
*

*
*
*
*
*

$0C*S,$10*S,$08*S,$05*S,$lD*5,$07*5,$05*5,$05*5

DC.W
•

A@

AA

etc. for regular set.

•

•
DC.W
DC.W

$01*5,$0E*S,$10*S,$00*S,$00*5,$00*S,$00*5,$00*5
$0A*S,$15*S,$0A*5,$15*S,$0A*S,$15*5,$0A*S,$00*S

DL

*

*
*
*

....

Alternate (A7) character set begins here.
DC.W
DC.W

$lF*5,$15*S,$15*5,$lF*S,$15*5,$15*5,$lF*S,$00*S
$08*5,$15*S,$02*S,$08*S,$15*S,$02*5,$00*S,$00*S

•
•

etc. for A7 set.

•
DC.W
DC.W

$01*5,$02*5,$02*5,$04*5,$08*5,$10*5,$10*5,$28*5
$00*5,$0"*S,$00*5,$0"*5,$0"*5,$00*S,$00*S,$3F*5

**
Char End EQO
DC.L
END

*
**
*
*

A@

AA

IPC
-1,-1

This is the end of our module.
No more modules follow this one.

DL

Preliminary DOS Manual

::GC 7901

Page A-6l

INSTALLING A NEW CURSOR
The 7900 Bitmap cursors,
Plot_and Alpha,
are each described
by a set of data. This set is pointed to by pointers in CMOS,
one pointer for the Plot cursor and one for the Alpha cursor •

.

Plotcur
Alphcur

EQU
EQU

$E40l6A
$E40l6E

The cursor descriptor data is a list of up to 32 long words.
Each long word describes the displacement of one pixel of the
cursor, with respect to the center pixel of the cursor.
The
list is terminated with a zero word. Since this zero word is
part of the descriptor, the center pixel of the cursor is always
ON.
The displacements are given as addresses in Bitmap memory.
Each
pixel in Bitmap memory corresponds to a word (two bytes) of
memory, so an X displacement of one pixel is produced by an
address displacement of two. (Positive X displacement is to the
right.) Similarly, a Y displacement of one pixel corresponds to
an address change of 2148 bytes (1024 pixels per Y line of the
screen, times two bytes per pixel). A positive Y displacement is
in the down direction.
A sample cursor might look like this,

pixels included in the cursor:

where

X's

correspond

to

X

XXX
X

The data list for this cursor would be:
+2
-2

+2148
-2148
1

(the
(the
(the
(the
(the

pixel to the right of center)
pixel to the left of center)
pixel below center)
pixel above center)
center pixel, and end of the list)

To install a new cursor, first define it in the form above.
Store this data in memory.
Then, alter "the pointer in CMOS
(either Plotcur or Alphcur) so that it points to your data.
Note that if you store your cursor in RAM other than CMOS, the
description will vanish when system power is turned off,' but the
CMOS pointer will remainl This will cause you to have NO cursor
at all. To reload CMOS defaults, use CTRL SHIFT Ml M2 RESET.

Preliminary DOS Manual

CGC 7998

Page A-62

*****************************************************************

*
*
*
*
*
*
*
*
*
*
*

Sample program PUTCURS
/'

Installs a new cursor as the Bitmap plot cursor.
This program stores its cursor descriptor in upper CMOS
memory, unused by current 7998 sofware. This may not be
compatible with future 7989 releases.

$lC3C

We run in DOS area

PUTCURS MOVE.L
MOVE.L

IHiCMOS,Al
ICursor,A3

Point to some unused CMOS
Point to our new cursor descriptor

PUT100p MOVE.L
TST.L
BNE.S

(A3) +, (Al) + Copy a long word into CMOS
-4 (A2)
Was it zero?
No, continue copying
PUT100p

ORG.L

Set up pointer to new cursor

MOVE.L

IHiCMOS,P1otcur

CLR.L
CLR.L
RTS

De
D1

Flag no error occurred
(We don't check for colon on line)
Return to DOS

HiCMOS EQU
P10tcur EQU

$E49E00
$E4016A

CMOS area (unused in TERMEM 1.1)
Plot cursor pointer

Cursor

-4*1924
-4*1024+2
-4*1024-2
-2*1024-4
-2*1924+4
-4
+4
+6
+8
-2*1924+8
-2*1024+19
-2*1924+12
-2*UJ24+14
-4*1924+18
-4*1924+12
-4*1924+14
-4*1024+16
4*1024

New cursor descriptor

DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L

Preliminary DOS Manual

X;C 7999

DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
DC.L
END

*
*
*

4*1924+2
4*1024-2
2*1124-4
2*1@24+4
2*1024+8
2*1924+18
2*1024+12
2*1924+14
4*1024+19
4*1924+12
4*1924+14
4*1924+16

"PUTCURS

(end of list)

Page A-63

CGC 79B9

.....

Preliminary DOS Manual

Page A-64

Preliminary DOS Manual

:GC 7900

Page A-65

DOS ERROR MESSAGES
rhe following errors may be reported by DOS.
an error message, load the error number
returning to DOS.
~rint

Error (hex)

To force DOS to
into D0.B before

Message

01
02
03
04
05
06

No index signal detected
No seek complete
Write fault
Drive not ready
Drive not selected
No track 000 detected

10
11
12
13
14
15
16
17
18
19
lA

ID read error
Uncorrectable data error found during a read
ID address mark not found
Data address mark not found
Block not found
Seek error
.
No host acknowledgement
Diskette write protected
Data field error found and corrected
Bad track found
Format error

20
21
22

Invalid disk controller command
Illegal logical block address
Illegal function for the specified drive

30

Diagnostic RAM error

40
41
42
43
44

Disk controller not ready
Controller time out error
Unable to determine controller error
Undefined controller state
Controller protocol sequence error

50
51
52
53
54
55

Undefined load error state
Record count error
Checksum error
Premature EOF during load
DOS buffer too small
Transient program size too small

60
61
62
63

End of file reached
File is write protected
Attempted to read thru density barrier
Attempted to transfer data on odd address

CGC 79""
7"

Unable to find requested file

88

Unable to create new f11e space

98

Unable to close requested file

AI
Al

81
82
83
84
85

. Empty slot found

Unable to update the directory

87

NO run address
Unable to find - disk
name
"Argument error
Attempt to a~cessa non-existant drive
Unable to initialize drive 1
Unable to initialize drive 2
Syntax errorl Missing argument

C8
C1
C2
C3
C4
C5
C6
C7
C8

Premature format termination
Error mapping routine not implemented
Unable to fetch this file
File is delete protected
File type error
File is execute only
File is to big to append
Insufficient stack size
I" mode is not allowed in argument filenames

B6

...

Preliminary DOS Manual

Page A-66

:X;C 790"

Preliminary DOS Manual

Page 11.-67

CGC 7999 .

Preliminary DOS Manual

Page A-68



---

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.3
Linearized                      : No
XMP Toolkit                     : Adobe XMP Core 4.2.1-c041 52.342996, 2008/05/07-21:37:19
Create Date                     : 2017:09:08 10:35:38-08:00
Modify Date                     : 2017:09:08 10:46:53-07:00
Metadata Date                   : 2017:09:08 10:46:53-07:00
Producer                        : Adobe Acrobat 9.0 Paper Capture Plug-in
Format                          : application/pdf
Document ID                     : uuid:d3ef61b5-f5f0-5947-8a06-af274569dd21
Instance ID                     : uuid:6b783611-c0c8-3e4f-9baa-f9bc393510fb
Page Layout                     : SinglePage
Page Mode                       : UseNone
Page Count                      : 212

EXIF Metadata provided by EXIF.tools