3.0. System Software

3.1. BASIC 10.0

                           C64DX BASIC 10.0

3.1.1. INTRODUCTION

     This section lists BASIC 10.0 commands, statements, and functions
in alphabetical order.  It gives a complete list of the rules (syntax)
of BASIC 10.0, along with a concise description of each.

COMMAND AND STATEMENT FORMAT

     The  commands  and  statements  presented  in  this  section  are
governed  by  consistent  format  conventions designed to make them as
clear as possible. In most cases, there are several actual examples to
illustrate  what the actual command looks like.  The following example
shows  some  of  the  format  conventions  that  are used in the BASIC
commands:

   EXAMPLE:   DLOAD <"program name"|(file_name_var)> [,U#] [,D#]
                |            |                         |     |
                |            |                         |     |
             keyword      argument (if any)       optional arguments

     The  parts of the command or statement that the user must type in
exactly  as they appear are in capital letters.  Words that don't have
to  be  typed  exactly,  such  as  the  name  of  the program, are not
capitalized.  When  quote marks (" ") appear (usually around a program
or  file name),  the user should include them in the appropriate place
according, to the format example.

     KEYWORDS,   also  called  RESERVED  WORDS,  appear  in  uppercase
letters.  THESE  KEYWORDS  MUST  BE  ENTERED  EXACTLY  AS THEY APPEAR.
However, many keywords have abbreviations that can also be used.

     Keywords  are  words that are part of the BASIC language that the
computer  understands.  Keywords  are the central part of a command or
statement.  They tell the computer what kind of action to take.  These
words cannot be used as variable names.

     ARGUMENTS   (also   called  parameters)  appear  in  lower  case.
Arguments  are  the  parts of a command or statement;  they complement
keywords  by  providing  specific  information  about  the  command or
statement.  For  example,  a  keyword  tells  the  computer  to load a
program,  while the argument tells the computer which specific program
to  load  and  a  second  argument  specifies  which  drive  the  disk
containing the program is in.  Arguments include filenames, variables,
line numbers, etc.

     SQUARE BRACKETS [] show OPTIONAL arguments.  The user selects any
or none of the arguments listed, depending on the requirements.

     ANGLE  BRACKETS <> indicates that the user MUST choose one of the
arguments listed.

     VERTICAL  BAR  |  separates items in a list of arguments when the
choices are limited to those arguments listed,  and no other arguments
can  be  used.  Then  the  vertical  bar appears in a list enclosed in
SQUARE BRACKETS, the choices are limited to the items in the list, but
still have the option not to use any arguments.

     ELLIPSIS  ...,  a sequence of three dots, means that an option or
argument can be repeated more than once.

     QUOTATION  MARKS  "  "  enclose character strings, filenames, and
other expressions. When arguments are enclosed in quotation marks in a
format,  the  quotation  marks  must  be included in a command file or
statement.  Quotation  marks  are  not  conventions  used  to describe
formats; they are required parts of a command or statement.

     PARENTHESES  ()  When  arguments are enclosed in parentheses in a
format,  they must be included in a command or statement.  Parentheses
are  not conventions used to describe formats; they are required parts
of a command or statement.

     VARIABLE  refers to any valid BASIC variable name such as X,  A$,
or T%.

     EXPRESSION means any valid BASIC expression,  such  as  A+B+2  or
.5*(X+3).



3.1.2. ALPHABETICAL LIST OF COMMANDS, FUNCTIONS, and OPERATORS

*           Token = AC        multiplication
+           Token = AA        addition
-           Token = AB        subtraction
/           Token = AD        division
<           Token = B3        less-than
=           Token = B2        equal
>           Token = B1        greater-than
^           Token = AE        exponentiation
(PI)        Token = FF        return value of PI

ABS         Token = B6        absolute function
AND         Token = AF        logical AND operator
APPEND      Token = FE,0E     append file
ASC         Token = C6        string to PETSCII function
ATN         Token = C1        trigonometric arctangent function
AUTO        Token = DC        auto line numbering
BACKGROUND  Token = FE,3B     background color
BACKUP      Token = F6        backup diskette
BANK        Token = FE,02     memory bank selection
BEGIN       Token = FE,18     start logical program block
BEND        Token = FE,19     end logical program block
BLOAD       Token = FE,11     binary load file from diskette
BOOT        Token = FE,1B     load & run ML, or BASIC autoboot
BORDER      Token = FE,3C     border color
BOX         Token = E1        draw graphic box
BSAVE       Token = FE,10     binary save to disk file
BUMP        Token = CE,03     sprite collision function
BVERIFY     Token = FE,28     verify memory to binary file
CATALOG     Token = FE,0C     disk directory
CHANGE      Token = FE,2C     edit program
CHAR        Token = E0        display characters on screen
CHR$        Token = C7        PETSCII to string function
CIRCLE      Token = E2        draw graphic circle
CLOSE       Token = A0        close channel or file
CLR         Token = 9C        clear BASIC variables, etc.
CMD         Token = 9D        set output channel
COLLECT     Token = F3        validate diskette (chkdsk)
COLLISION   Token = FE,17     enable BASIC event
COLOR       Token = E7        set screen colors
CONCAT      Token = FE,13     concatenate two disk files
CONT        Token = 9A        continue BASIC program execution
COPY        Token = F4        copy a disk file
COS         Token = BE        trigonometric cosine function
CUT         Token = E4        cut graphic area
DATA        Token = 83        pre-define BASIC program data
DCLEAR      Token = FE,15     mild reset of disk drive
DCLOSE      Token = FE,0F     close disk channel or file
DEC         Token = D1        decimal function
DEF         Token = 96        define user function
DELETE      Token = F7        delete BASIC lines or disk file
DIM         Token = 86        dimension BASIC array
DIR         Token = EE        disk directory
DISK        Token = FE,40     send disk special command
DLOAD       Token = F0        load BASIC program from disk
DMA         Token = FE,1F     define & execute DMA command
DMA         Token = FE,21     "
DMA         Token = FE,23     "
DMODE       Token = FE,35     set graphic draw mode
DO          Token = EB        start BASIC loop
DOPEN       Token = FE,0D     open channel to disk file
DPAT        Token = FE,36     set graphic draw pattern
DSAVE       Token = EF        save BASIC program to disk
DVERIFY     Token = FE,14     verify BASIC memory to file
ELLIPSE     Token = FE,30     draw graphic ellipse
ELSE        Token = D5        if/then/else clause
END         Token = 80        end of BASIC program
ENVELOPE    Token = FE,0A     define musical instrument
ERASE       Token = FE,2A     delete disk file
ERRS        Token = D3        BASIC error function
EXIT        Token = FD        exit BASIC loop
EXP         Token = BD        exponentiation function
FAST        Token = FE,25     set system speed to maximum
FILTER      Token = FE,03     set audio filter parameters
FIND        Token = FE,2B     hunt for string in BASIC program
FN          Token = A5        define user function
FOR         Token = 81        start BASIC for/next loop
FOREGROUND  Token = FE,39     set foreground color
FRE         Token = B8        available memory function
GCOPY       Token = FE,32     graphic copy
GENLOCK     Token = FE,38     set video sync mode
GET         Token = Al        receive a byte of input
GO          Token = CB        program branch
GOSUB       Token = 8D        program subroutine call
GOTO        Token = 89        program branch
GRAPHIC     Token = DE        set graphic mode
HEADER      Token = F1        format a diskette
HELP        Token = EA        display BASIC line causing error
HEX$        Token = D2        return hexadecimal string function
HIGHLIGHT   Token = FE,3D     set highlight color
IF          Token = 8B        if/then/else conditional
INPUT       Token = 85        receive input data from keyboard
INPUT#      Token = 84        receive input data from channel (file)
INSTR       Token = D4        locate a string within a string
INT         Token = B5        integer function
JOY         Token = CF        joystick position function
KEY         Token = F9        define or display function key
LEFT$       Token = C8        leftmost substring function
LEN         Token = C3        length of string function
LET         Token = 88        variable assignment
LINE        Token = E5        draw graphic line, input line
LIST        Token = 9B        list BASIC program
LOAD        Token = 93        load program from disk
LOCATE      Token = E6                (currently unimplemented)
LOG         Token = BC        natural log function
LOOP        Token = EC        end of do/loop
LPEN        Token = CE,04     lightpen position function
MID$        Token = CA        substring function
MONITOR     Token = FA        enter ML Monitor mode
MOUSE       Token = FE,3E     set mouse parameters
MOVSPR      Token = FE,06     set sprite position and speed
NEW         Token = A2        clear BASIC program area
NEXT        Token = 82        end of for-next loop
NOT         Token = A8        logical complement function
OFF         Token = FE,24             (subcommand)
ON          Token = 91        multiple branch or subcommand
OPEN        Token = 9F        open I/O channel
OR          Token = B0        logical or function
PAINT       Token = DF        graphic flood-fill
PALETTE     Token = FE,34     set palette color
PASTE       Token = E3        draw graphic area from cut buffer
PEEK        Token = C2        return memory byte function
PEN         Token = FE,33     set graphic pen color
PIC         Token = FE,37     graphic subcommand
PLAY        Token = FE,04     play musical notes from string
POINTER     Token = CE,0A     address of string var function
POKE        Token = 97        change memory byte
POLYGON     Token = FE,2F     draw graphic polygon
POS         Token = B9        text cursor position function
POT         Token = CE,02     return paddle position
PRINT       Token = 99        display data on text screen
PRINT#      Token = 98        send data to channel (file)
PUDEF       Token = DD        define print-using symbols
QUIT        Token = FE,1E             (currently unimplemented)
RCLR        Token = CD                (currently unimplemented)
RDOT        Token = D0                (currently unimplemented)
READ        Token = 87        read program pre-defined program data
RECORD      Token = FE,12     set relative disk file record pointer
REM         Token = 8F        BASIC program comment
RENAME      Token = F5        rename disk file
RENUMBER    Token = F8        renumber BASIC program lines
RESTORE     Token = 8C        set DATA pointer, subcommand
RESUME      Token = D6        resume BASIC program after trap
RETURN      Token = 8E        end of subroutine call
RGR         Token = CC                (currently unimplemented)
RIGHT$      Token = C9        rightmost substring function
RMOUSE      Token = FE,3F     read mouse position
RND         Token = BB        pseudo random number function
RREG        Token = FE,09     return processor registers after SYS
RSPCOLOR    Token = CE,07     return sprite color function
RSPPOS      Token = CE,05     return sprite position function
RSPRITE     Token = CE,06     return sprite parameter function
RUN         Token = 8A        run BASIC program from memory or disk
RWINDOW     Token = CE,09     return text window parameter function
SAVE        Token = 94        save BASIC program to disk
SCALE       Token = E9                (currently unimplemented)
SCNCLR      Token = E8        erase text or graphic display
SCRATCH     Token = F2        delete disk file
SCREEN      Token = FE,2E     set parameters or open graphic screen
SET         Token = FE,2D     set system parameter, subcommand
SGN         Token = B4        return sign of number function
SIN         Token = BF        trigonometric sine function
SLEEP       Token = FE,0B     pause BASIC program for time period
SLOW        Token = FE,26     set system speed to minimum
SOUND       Token = DA        perform sound effects
SPC         Token = A6        skip spaces in printed output
SPRCOLOR    Token = FE,08     set multicolor sprite colors
SPRDEF      Token = FE,1D             (currently unimplemented)
SPRITE      Token = FE,07     set sprite parameters
SPRSAV      Token = FE,16     set or copy sprite definition
SQR         Token = BA        Square root function
STEP        Token = A9        for-next step increment
STOP        Token = 90        halt BASIC program
STRS        Token = C4        string representation of number function
SYS         Token = 9E        call ML routine
TAB         Token = A3        tab position in printed output
TAN         Token = C0        trigonometric tangent function
TEMPO       Token = FE,05     set tempo (speed) of music play
THEN        Token = A7        if/then/else clause
TO          Token = A4                (subcommand)
TRAP        Token = D7        define BASIC error handler
TROFF       Token = D9        BASIC trace mode disable
TRON        Token = D8        BASIC trace mode enable
TYPE        Token = FE,27     display sequential disk file
UNTIL       Token = FC        do/loop conditional
USING       Token = FB        define print output format
USR         Token = B7        call user ML function
VAL         Token = C5        numeric value of a string function
VERIFY      Token = 95        compare memory to disk file
VIEWPORT    Token = FE,31             (currently unimplemented)
VOL         Token = DB        set audio volume
WAIT        Token = 92        pause program pending memory condition
WHILE       Token = ED        do/loop conditional
WIDTH       Token = FE,1C             (currently unimplemented)
WINDOW      Token = FE,1A     set text screen display window
XOR         Token = CE,08     logical xor function



3.1.3. BASIC 10.0 COMMAND AND FUNCTION DESCRIPTION


ABS -- Absolute value function

                           ABS (expression)

The  ABSolute value function returns the unsigned value of the numeric
expression.

                X = ABS(1)              Result is X = 1
                X = ABS(-1)             Result is X = 0


AND -- Boolean operator

                      expression AND expression

The  AND  operator returns a numeric value equal to the logical AND of
two  numeric  expressions,  operating  on  the  binary value of signed
16-bit  integers in the range (-32768 to 32767).  Numbers outside this
range result in an 'ILLEGAL QUANTITY' error.

                X = 4 AND 12            Result is X=4
                X = 8 AND 12            Result is X=8
                X = 2 AND 12            Result is X=0

In  the  case  of  logical  comparisons,  the  numeric value of a true
situation  is  -1  (equivalent  to 65535 or $FFFF hex) and the numeric
value of a false situation is zero.

  X = ("ABC"="ABC") AND ("DEF"="DEF") Result is X=-l (true)
  X = ("ABC"="ABC") AND ("DEF"="XYZ") Result is X= 0 (false)


APPEND -- Open a disk file and prepare to append data to it

   APPEND# logical_file_number, "filename" [,Ddrive] [<ON|,>Udevice]

Opens  filename for writing, and positions the file pointer at the end
of  the  file. Subsequent PRINT# statements to the logical_file_number
will  cause  data  to be appended to the end of this file. If the file
does not exist, it will be created.

APPEND#1, "filename"
APPEND#1, (file$), ON U(unit)


ASC -- PETSCII value function

                             ASC (string)

This   function  returns  the  PETSCII  numeric  value  of  the  first
character of a string.  The PETSCII value of an empty (null) string is
zero. This function is the opposite of the CHR$ function. Refer to the
Table of PETSCII Character Codes.

                 X = ASC("ABC")         Result is X=65
                 X = ASC("")            Result is X=0


ATN -- Arc tangent function

                           ATN (expression)

This  function  returns  the  angle  whose tangent is the value of the
numeric  expression,  measured  in radians. The result is in the range
of -PI/2 to PI/2 radians.

                X = ATN(45)             Result is X=1.54050257

To  get  the arc tangent of an angle measured in degrees, multiply the
numeric expression by PI/180.


AUTO -- Enable or disable automatic line numbering

                           AUTO [increment]

Turns  on  the automatic line numbering feature which eases the job of
entering  programs  by  typing  the line numbers for the user. As each
program  line  is entered by pressing <RETURN> the next line number is
printed  on  the  screen,  with the cursor in position to begin typing
that  line.  The  increment  parameter refers to the increment between
line  numbers.  AUTO  with  no  increment  given  turns  off auto line
numbering.  AUTO  mode is also turned off automatically when a program
is RUN. This statement is executable only in direct mode.

  AUTO 10   automatically numbers line in increments of ten.
  AUTO 50   automatically numbers line in increments of fifty.
  AUTO      turns off automatic line numbering.


BACKGROUND -- Set the background color of the display

                           BACKGROUND color

Sets  the  screen background color to the given color. The color given
must be in the range (0-15). See the Color Table.


BACKUP -- Backup an entire disk from one drive to another

BACKUP Dsource_drive TO Ddestination_drive [<ON|,>Udevice]

This  command  copies all the files on a diskette to another on a dual
drive  system  only.  It  cannot backup diskettes using CBM serial bus
type  drives, for example. If the destination diskette is unformatted,
BACKUP  will  automatically  format it. BACKUP copies every sector, so
any  data  already on the destination diskette will be overwritten. To
copy specific files from one drive to another, use the COPY command.

NOTE:  This  command  can only be used with a dual disk drive, such as
the  built-in  C64DX  drive and optional F016-type expansion drive. To
backup  diskettes  using  different drives, such as the built-in drive
and a 1581-type serial bus drive, use a utility program.

BACKUP D0 to D1              Copies all files from the disk in
                             drive 0 to the disk in drive 1.

BACKUP D0 TO D1, ON U9       Copies all files from drive 0 to
                             drive 1 in disk drive unit 9.


BANK -- Set the memory bank number for PEEK, POKE, SYS, WAIT, LOAD, SAVE

                           BANK memory_bank

                 [*** THIS COMMAND MIGHT CHANGE ***]

This  command  should  be  used  before  and BASIC command that has an
address  parameter.  The  address  parameters are limited to the range
(0-65535,  $0000-$FFFF hex). The BANK command tells the computer which
64K byte memory bank the location you want is in.

The  memory_bank  parameter  is number from 0-255. Refer to the System
memory  map  to  see  what is in each bank. A BANK number greater than
127  (i.e.,  has  its most significant bit set) means "use the current
system  configuration",  and  must  be used to access an I/O location.
BASIC defaults to BANK 128.

For examples, see PEEK, POKE, etc.


BEGIN/BEND -- Extend an IF clause over more than one line

BEGIN/BEND  are  used to define a block of code which is considered by
the IF statement to be one statement.

The normal usage of IF/THEN/ELSE would be along the following lines:

        IF boolean THEN statement(s) : ELSE statement(s)

The  main  restriction  is  that  the  entire body of the IF/THEN/ELSE
construct  can  only  occupy  one  line.  BEGIN/BEND allows either the
'THEN' or the 'ELSE' clause to run on for more than one line.

        IF boolean THEN BEGIN: statements...
                               statements...
                               statements...  BEND : ELSE BEGIN
                               statements...
                               statements...  BEND

Remember, however, that this is only a way to extend the body for more
than one line: all other 'IF/THEN' rules apply. For example:

100 IF x=1 THEN BEGIN : a=5
110 :  b=6
120 :  c=7
130 BEND : print "ah-ha!"

In the above example, "ah-ha!" would be printed ONLY if the expression
'x=1' is TRUE, because the print statement is on the same logical line
as the THEN clause.

It is bad practice to GOTO a line in the middle of a BEGIN-BEND block.
If  BEGIN or BEND is encountered outside of an active IF statement, it
is ignored.


BLOAD -- loads a binary disk file into memory

         BLOAD "filename" [,Bbank] [,Paddress] [<ON|,>Udevice]

Used  to load a machine language program or other binary data (such as
display  pictures  or  sprite  data) into memory. If a load address is
not  given, the load address given in the disk file will be used. If a
bank  number  is  not given, the bank given in the last BANK statement
will be used.  If a load overflows a bank  (that is,  the load address
exceeds 65535 ($FFFF)), an 'OUT OF MEMORY' error is reported. Also see
the LOAD command.

                BLOAD "sprites", P(dec("600")), B0


BOOT -- Load and execute a program

    BOOT
    BOOT SYS
    BOOT filename [,Bbank] [,Paddress] [,Ddrive] [<ON|,>Udevice]

BOOT  without a filename given causes the computer to look for a BASIC
program  called  AUTOBOOT.C65* on the indicated diskette,  LOAD it and
RUN it (just like RUN "AUTOBOOT.C65*").

BOOT with a filename given will cause the executable binary file to be
BLOADed and executed beginning at the load address.  If a load address
is  not  given,  the  file  will  be loaded and execution begun at the
address stored on disk.

BOOT  SYS is a special command that copies the "home" sector (the very
track  and  sector) of the C64DX built-in drive into memory at address
$400 to $5FF  (one physical sector,  512 bytes)  and perform a machine
language  JSR  (Jump  SubRoutine)  to it.  It has the same function as
turning  on  your C64DX while holding down the ALT key.  It is used to
boot  an alternate operating system from either a CBM 3.5" diskette or
an  MSDOS (720K) diskette.  If used in a BASIC program,  and it fails,
the  system  can  be corrupted. BOOT SYS does *not* use the normal DOS
to access the disk.

        BOOT            Loads & runs BASIC program called
                        AUTOBOOT.C65* on system disk.

        BOOT U9         Loads & runs BASIC program called
                        AUTOBOOT.C65* on disk unit 9.

        BOOT "ml"       Load & executes machine language
                        program called ML, starting at address
                        stored on disk.


BORDER -- Set the exterior border color of the display

                             BORDER color

Sets  the screen border color to given color. The color must be in the
range (0-15). See the Color Table.


BOX -- Draw a 4-sided graphical shape

                 BOX x0,y0, x1,y0, x0,y1, x1,y1 [,solid]

Requires  two  line  segments  to  be  specified,  the  order of which
determines  the  shape  drawn.  The  shape  is  drawn in the currently
specified  PEN  color,  on  the  currently specified SCREEN. The above
command will draw the following shape:

               |0,<=0 +--------------------+ |1,<=0
                      |                    |
                      |                    |
               |0,<=1 +--------------------+ |1,<=1

But if the order of the coordinates were given as:

                BOX x0,y0, x1,y0, x1,y1, x0,y1

a "bowtie" shape would be drawn. See the sample program at SCREEN.


BSAVE -- Save an area of memory in binary disk file

   BSAVE "[@]filename", Pstart_adr TO Pend_adr [,Bbank] [,Ddrive]
         [<ON|,>Udevice]

BSAVE  copies  an  area  of  memory  into  a  binary  disk file called
"filename",  starting  at  start_adr  and  ending  at  end_adr-1 (i.e.
end_adr  must  be one more than actual last address saved).  If a bank
number  is  not given,  the bank given in the last BANK statement will
be used.  end_adr must be greater than start_adr, and area to be saved
must  be  limited  to the indicated memory bank.  You cannot save data
from  more than one bank at a time.  start_adr is saved on disk as the
load  address.  If filename already exists on the designated diskette,
memory  is NOT saved and a 'FILE EXISTS' error is reported.  Preceding
the  filename with an '@'-sign will allow you to overwrite an existing
file, but see the cautions at DSAVE.

     BSAVE "sprites", P(dec("600")) TO P(dec("800")), B0


BUMP -- Sprite collision function

                         BUMP (type)

This   function   return   a  numeric  summary  of  sprite  collisions
accumulated since the last time the BUMP function was used.

You  can use the COLLISION command to set up a special routine in your
program to receive control whenever a sprite BUMPs into something, but
a  particular  COLLISION does not have to be enabled to use BUMP.  See
the COLLISION command.

To  evaluate  sprite  collisions,  where  a  BIT position (0-7) in the
numeric result corresponds to a sprite number (0-7):

     BIT position:           7 6 5 4 3 2 1 0
                             | | | | | | | |
     BUMP value in binary:   0 0 0 0 0 1 0 1   = 5 decimal

BUMP(1) returns a value representing sprite-to-sprite collisions.
BUMP(2) returns a value representing sprite-to-data collisions.

     X = BUMP(1)     Result is X=3 if sprites 0 & 1 collided,
                     as shown above. (binary 101 = 5 decimal).

Note  that more than one collision can be recorded,  in which case you
should  evaluate  a  sprite's  position  using  the RSPPOS function to
figure  out  which  sprite  collided  with what. BUMP is reset to zero
after each use.


BVERIFY -- Compare a binary disk file to an area of memory

  BVERIFY "filename" [,Paddress] [,Bbank] [,Ddrive] [<ON|,>Udevice]

BVERIFY  compares  a  binary disk file called "filename" to an area of
memory. In direct mode, if the areas contain the same data the message
"OK"  is displayed, and if the data differs the message 'VERIFY ERROR'
is displayed.

In  program  mode,  an  error  is  generated  if  a  mismatch is found
otherwise  the program continues normally.  The comparison starts with
the address given,  else it starts at the address stored on disk.  The
comparison ends when the last byte is read from the disk file.

If  a  bank  number  is  not  given,  the  bank given in the last BANK
statement  will  be  used.  The  ending  address  is determined by the
length of the disk file. The comparison halts on the first mismatch or
at  the  end of the file.  The area to be compared must be confined to
the indicated memory bank.

                 BVERIFY "sprites", P(dec("600")), B0


CATALOG -- see DIR (DIRECTORY) command


CHANGE -- Find text in a BASIC program and change it.

             CHANGE :string1: TO :string2: [,line_range]
             CHANGE "string1" TO "string2" [,line_range]

This is a direct (edit) mode command. CHANGE looks for all occurrences
of string1 in the program,  displays each line containing string1 with
the  target  string  highlighted,  and prompts the user for one of the
following:

       Y<RETURN>       Yes, change it and look for more
       N<RETURN>       No, don't change it, but look for more
       *<RETURN>       Yes, change all occurrences from here on
       <RETURN>        Exit command now, don't change anything

Any character can be used for the string delimiter, but there are side
effects: see comments at FIND command. If the line number range is not
given  (see  LIST  for  description  of  range parameter),  the entire
program is searched.


CHAR -- Draw a character string on a graphic screen

  CHAR column, row, height, width, direction, "string" [,charsetadr]

                 [*** THIS IS SUBJECT TO CHANGE ***]

CHAR  displays  text  on  a  graphic  screen  at a given location. The
character   height,   width,   and  direction  are  programmable.  The
parameters are defined as:

     column:         Character position:
                             For 320 wide screens, 0-39
                             For 640 wide screens, 0-79
     row:            Pixel line:
                             For 200 line screens, 0-199
                             For 400 line screens, 0-399
     height:                 Multiple of 8-bit character height:
                             1= 8 pixels high, 2= 16 pixels, etc.
     width:          Multiple of 8-bit character width:
                             1= 8 pixels high, 2- 16 pixels, etc.
     direction:      Bit mask:       B0= up
                                     B1= right
                                     B2= down
                                     B3= left

The  string can consist of any printable character,  as defined by the
VIC  character  set.  Non-text characters are ignored.  If the address
of  the character set is not given,  the upper/lower ROM character set
is used ($29800).

                CHAR 18,96, 1,1,2, "C65D", DEC("9000")

The  above  example will draw the characters "C65D" in the center of a
320x200  pixel  screen  using the system's uppercase/graphic character
set.


CHR$ -- Character string function

                             CHR$ (value)

This  function  returns  a  string of one character having the PETSCII
value  specified.  This  function is the opposite of the ASC function.
It's  often  used in PRINT strings to output data that is not visible,
such  as  control  codes  and escape sequences.  Refer to the Table of
PETSCII Character Codes.

     PRINT CHR$(27)"Q";     CHR$(27) is the escape character.
                            This statement performs the
                            clear-to-end-of-line escape function.


CIRCLE -- Draw a circle on a graphic screen

              CIRCLE x_center, y_center, radius [,solid]

The  CIRCLE  command will draw a circle with the given radius centered
at (x_center,y_center) on the current graphic screen.  The circle will
be filled (i.e., a disc) if SOLID is non-zero.

                          CIRCLE 160,100,50

The  above example will draw a circle in the center of a 320x200 pixel
screen (160,100) having a radius of 50 pixels. The aspect ratio of the
screen  may  cause it to appear as an ellipse,  however.  See also the
ELLIPSE command.


CLOSE -- Close a logical I/O channel

                     CLOSE logical_channel_number

This command closes the input/output channel associated with the given
logical_channel_number, established by an OPEN statement.  In the case
of  buffered  output (such as the serial bus or RS232) any data in the
device's  buffer  will  be  transmitted  before the channel is closed.
Refer to specific I/O operations for details.

The  logical_channel_number  is  required;  to close all channels on a
given device,  use the DCLOSE  command.  Note that RUN,  NEW,  and CLR
commands  will  initialize  the  logical  channel  tables but will not
actually close any channels.


CLR -- Clear program variables

                                 CLR

This  statement initializes BASIC's variable list, setting all numeric
variables  to  zero and string variables to null.  It also initializes
the  DATA  pointer,  BASIC  runtime  stack pointer  (i.e.,  clears all
GOSUBs, DO/LOOPs, FOR/NEXT loops, etc.), and clears any user functions
(DEF  FNx).  Any  OPEN  channels  are  forgotten  (but  a CLOSE is not
performed; don't use if there are any open disk output files). A CLeaR
is automatically performed by a RUN or a NEW command.


CMD -- Set default output channel

                 CMD logical_channel_number [,string]

CMD  changes the default output device,  normally the screen,  to that
specified.  The  logical_channel_number  can  be any previously OPENed
write channel, such as one to a disk file, printer, or RS232.

When  redirected  via  CMD,  all output which normally would go to the
screen (such as PRINT commands,  LIST output,  DIRECTORY lists,  etc.)
is sent to another device or file.

The  redirection  is  terminated  by  CLOSE-ing  the  CMD  channel  or
executing  a PRINT# to the CMD channel.  Some output devices require a
PRINT#  to  be  performed  before  the CMD channel is closed,  such as
printers,   to   cause  the  device's  buffer  to  be  flushed  (i.e.,
displayed).

Any  system  error  will  redirect  output back to the system default,
normally the screen, but will not flush nor close the output channel.

If  the  optional  string is given, it is output immediately after the
CMD  device  is  established.  This feature is normally used to set up
printers  (eg., set printer modes via escape codes) or to identify the
output (eg., title printouts).

      OPEN 4,4        OPENS device #4, which is the printer.
      CMD 4           All normal output now goes to the printer.
      LIST            The LISTing goes to the printer.
      PRINT#4         Set output back to the screen.
      CLOSE 4         Close the printer channel.


COLLECT -- Check (validate) disk, delete bad files and free lost sectors

                   COLLECT [Ddrive] [<ON|,>Udevice]

Refer  to the DOS 'V'alidate command.  This command will cause the DOS
to recalculate the Block Availability Map (BAM) of the diskette in the
indicated  drive,  allocating  only those sectors being used by valid,
properly  closed  files.  All  other  sectors are marked as "free" and
improper files are automatically deleted.

Note:  COLLECT should be used with extreme care,  and MUST NOT be used
on  diskettes with special boot sectors or direct access (eg., random)
files. In any case, be sure the diskette has been BACKUP-ed first.


COLLISION -- Setup subroutine to handle special events

                     COLLISION type [,linenumber]

                     [*** THIS MIGHT CHANGE ***]

COLLISION  is  used to handle "interrupt" situations in BASIC, such as
sprites  bumping into things or lightpen triggers.  When the specified
situation occurs, BASIC will finish processing the currently executing
instruction and perform an automatic GOSUB to the linenumber given.

When  the subroutine terminates (it must end with a RETURN) BASIC will
resume  processing  where  it  left off.  Interrupt handling continues
until  a  COLLISION  of  the  same  type but without any linenumber is
specified.  More  than  one  type interrupt may be enabled at the same
time,  but  only  one  interrupt  can  be handled at a time  (i.e., no
recursion and no nesting of interrupts). The type interrupt can be:

                1 = Sprite to sprite collision
                2 = Sprite to display data collision
                3 = Light pen

Note that what caused an interrupt may continue causing interrupts for
some  time  unless  the  situation  is  altered  or  the  interrupt is
disabled.  This is especially true for BASIC, which is slow to respond
to  interrupts.  Use  the  BUMP  and  RSPPOS functions to evaluate the
results  of  sprite collisions,  and the LPEN function to evaluate the
position of a light pen.

           10 COLLISION 1,90
           20 SPRITE 1,1 : MOVSPR 1,100,100 : MOVSPR 1,0#5
           30 SPRITE 2,1 : MOVSPR 2,100,150 : MOVSPR 2,180#5
           40 DO : PRINT : LOOP
           50 END
           90 PRINT"BUMP! ";:RETURN

In  this  example,  sprite-to-sprite collisions are enabled (line 10),
and  two  sprites  are turned on,  positioned, and made to move (lines
20  &  30).  One  sprite  moves  up and the other moves down while the
program  does nothing other than print blank lines to the screen (line
40).  When the sprite collide, the subroutine at line 90 is called, it
prints "BUMP!", and the computer goes back to printing blank lines.


COLOR -- Enable or disable screen color (character attribute) control

                            COLOR <ON|OFF>

COLOR  turns  on  or  turns off the screen editor's attribute handler.
When  colors  are  turned off, whatever character attributes are being
currently  displayed (text color, underline, flash, etc.) are "stuck".
The  main  purpose  for  doing  this  is  to  speed up screen handling
(writing to the screen or scrolling the screen) about two times, since
the  screen  editor  no  longer has to manipulate the attributes. Note
that only FOREGROUND colors (and special VIC attributes) are affected.

To change screen colors, use the following commands:

         FOREGROUND color#       Set Foreground color (text)
         HIGHLIGHT color#        Set Highlight color (text)
         BACKGROUND color#       Set VIC background color
         BORDER color#           Set VIC border color


CONCAT -- Concatenate (merge) two sequential disk files

    CONCAT "file1"[,Ddrive1] TO "file2"[,Ddrive2] [<ON|,>Udevice]

CONCAT  merges two SEQuential files, appending the contents of "file1"
to "file2".  Upon completion, "file2" contains the data of both files,
and  "file1" is unchanged.  Both files must exist on drives of the the
same unit, and pattern matching is not allowed.

Some  disk  drives handle CONCAT differently;  refer to the DOS manual
for specific details.


CONT -- Continue program execution

                                 CONT

CONTinue is used to re-start a BASIC program that was halted by a STOP
or END statement,  or interrupted by the <STOP> key.  The program will
resume  at  the statement following the STOP or END instruction, or at
the  statement  after  the one that was interrupted by the <STOP> key.
CONT  is  typically used during program debugging. You can look at and
alter variables while the program is halted.

Programs  halted as a result of an untrapped error condition cannot be
CONTinued.  Programs  that  have  been  edited  in  any  way cannot be
restarted.  Any  error  condition  that  occurs  since the program was
halted  will prevent it from being restarted.  Programs that cannot be
restarted via CONT can be restarted with a GOTO,  as long as you don't
need  to  resume execution in the middle of a line of commands and you
recall where the halt occurred.

Note that the <STOP> key can interrupt some commands in mid-execution,
such as file I/O, drawing commands, etc.  In such cases,  programs may
not run correctly after a CONTinue.


COPY -- Copy disk files

       COPY ["file1"][,Dd1] TO ["file2"][,Dd2] [<ON|,>Udevice]

COPYs  a  disk file to another disk file.  On single drive units,  the
filenames  must  be different.  On  dual  drive units,  copying can be
done between two drives on the same unit, and the filenames can be the
same  or different.  Pattern matching can be used.  Copying files from
one  unit  to  a  different  unit  cannot  be done: use a copy utility
program  in  such  cases.  Only legal type files can be copied; direct
access data, boot sectors, and partitions cannot be copied.

Refer to the DOS manual for your disk drive specific details.

     COPY "file1" TO (F2$)         Copies "file1" to another file
                                   whose name is in F2$ on the
                                   same drive. Names must differ.

     COPY "file1",D0 TO D1,U9      Copies "file1" from unit 9
                                   drive-0 to unit 9 drive-1.

     COPY D0 TO D1                 Copies all files from drive-0
                                   to drive-1 on the same unit.

     COPY "???.src",D0 TO "*",D1   Copies all files on drive-0
                                   matching the pattern to a file
                                   of the same name on drive-1.


COS -- Cosine function

                           COS (expression)

This  function  returns the cosine of X,  where X is an angle measured
in radians. The result is in the range -1 to 1.

           X = COS (pi)                Result is X=-1

To  get  the cosine  of  an  angle  measured in degrees,  multiply the
numeric expression by pi/180.


CUT -- Cut a graphic area into a temporary structure

                            CUT x,y,dx,dy

                    [*** NOT YET IMPLEMENTED ***]


DATA -- Define program constant data to be accessed by READ command

                       DATA [list of constants]

DATA  statements  store  lists  of  data  that will be accessed during
program  execution  by a READ statement. The DATA statement can appear
anywhere  in  the  program,  and  it is never executed.  BASIC keeps a
pointer  to  the  earliest  un-READ  DATA  statement, and data is read
sequentially  from  first  item  in a DATA statement to the last item,
from  the  earliest  DATA  statement  in  the program to the last DATA
statement in the program.

The  list  of  constants  can  contain  both numeric data  (integer or
floating point) and string data,  but cannot contain expressions which
must be evaluated  (such as 1+2, DEC("1234"), or CHR$(13)).  Items are
separated by commas. String data need not be enclosed in quotes unless
it  contains  certain  characters,  such  as  spaces,  commas, colons,
graphic  characters,  or  control codes.  If two commands have nothing
between them, the data will be READ as 0 if numeric or a null string.

The  RESTORE  command allows you to position BASIC's data pointer to a
specific  line  number.  If  the  program tries to read more DATA than
exists  in  the  program,  an 'OUT  OF DATA' error results.  If a READ
statement's  variable  type does not agree with the DATA being read, a
'TYPE MISMATCH' error results.

      DATA 100, 200, FRED, "HELLO, MOM", , 3.14, ABC123, -1.7E-9


DCLEAR -- Clear all open channels on disk drive

                   DCLEAR [Ddrive] [<ON|,>Udevice]

DCLEAR  sends  the indicated disk drive an 'I'nitialize command.  This
clears all open channels, closes all open files, and causes the DOS to
re-read  the  diskette's  Block Allocation Map (BAM). Note that DCLEAR
DOES  NOT  close open channels on the computer's side  (see the DCLOSE
command).  There  are  some  other side affects caused by this command
with different types of drives  --  refer the DOS manual for your disk
drive for specific details.


DCLOSE -- Close a disk file, or close all channels on a device

            DCLOSE [#logical_file_number] [<ON|,>Udevice]

DCLOSE  is  intended  to  close  a file opened with the DOPEN command.
Specific  files  can be closed by specifying a logical_file_number, or
all  files  on  a  particular  drive can be closed by not specifying a
particular logical_file_number.

It is possible to close channels on non-disk devices with this command
by specifying only the device number.

       DCLOSE#1        Closes the file associated with logical
                       logical file number 1.
       DCLOSE          Closes all files currently open on the
                       default system drive.
       DCLOSE U(U2)    Closes all channels open to device U2.


DEC -- Decimal value function

                          DEC (hex_string)

This  function  return  the  decimal  value of a string representing a
hexadecimal number in the range  "0000"  to  "FFFF".  The result is in
the range  0-65535.  If the string contains a non-hexadecimal digit or
is  more  than  four  (4)  characters  in length an 'ILLEGAL QUANTITY'
error is reported.

          VIC = DEC("D000")       Result is VIC=53248,
                                  the address of the VIC chip


DEF FN -- Define function

          DEF FN name(numeric_variable) = numeric_expression

Define a user-written numeric function.  The DEF FNx statement must be
executed  before  the  function can be used.  Once a function has been
defined,  it can be used like any other numeric variable. The function
name   is  the  letters  FN  followed  by  any  legal  floating  point
(non-integer)  variable  name.  A  function  can  be defined only in a
program.

The  numeric_variable is a "dummy" variable. It names the variable the
numeric_expression  which  will be replaced when the function is used.
It's not required to be used in the numeric_expression,  and its value
won't be changed by the function call.

The  numeric_expression  performs the calculations of the function. It
is any legal numeric expression that fits on one line.  Variables used
in the expression have their value at the time the function is used.

Functions  can  be used only by the program which defines them. If one
program  chains  to  another  program,  the  first program's functions
cannot be used (usually a 'SYNTAX ERROR' results).  Similarly,  if the
program  is  moved  in  any  way  after  the  function is defined, the
function cannot be used.

10 DEF FN R(MAX) = INT(RND(0)*MAX)+1
20 INPUT "MAXIMUM"; MAX
30 PRINT FN R(MAX)

In  this example,  we've defined a function which will return a pseudo
random  number  between  1  and whatever MAX is.  Instead of using the
expression INT(RND(0)*MAX)+1 every time a random number is needed,  we
can now use FN R(MAX).  When we use FN R(x),  the value of 'x' will be
substituted everywhere MAX is used in the function definition.

10 DEF FN I(X) = X+1
20 DEF FN L(Z) = LEN(A$)
30 DEF FN AVG(N) = (TOT*CNT+N)/(CNT+1)


DELETE -- Delete lines of BASIC program, or
          Delete disk files

          DELETE [startline] [-[endline]]
          DELETE "filespec" [,Ddrive] [<ON|,>Udevice] [,R]

There  are  two forms of DELETE. The first form is used in direct mode
to remove lines from a BASIC program:

    DELETE 75      Deletes line 75
    DELETE 10-50   Deletes line 10 through 50 inclusive.
    DELETE -50     Deletes all lines from the beginning of
                   the program up to and including line 50.
    DELETE 75-     Deletes all lines from 75 to the end of
                   the program.

The  second  form  is  used in program or direct mode to delete a disk
file. See the SCRATCH command.

    DELETE "myfile"   Deletes the file MYFILE on the system drive.


DIM -- Declare array dimensions

         DIM variable(subscripts) [,variable(subscripts)]...

Before arrays of variables can be used, the program must first execute
a  DIM  statement  to establish DIMensions of that array (unless there
are 11 or fewer elements in the array).  The statement DIM is followed
by the name of the array,  which may be any legal variable name. Then,
enclosed  in  parentheses,  put  the  number  (or numeric variable) of
elements  in each dimension.  An array with more than one dimension is
called  a  matrix.  Any number of dimensions may be used,  but keep in
mind  that the whole list of variables being created takes up space in
memory,  and it is easy to run out of memory if too many are used.  To
figure  the  number  of variables created with each DIM,  multiply the
total  number of elements in each dimension of the array.  Note:  each
array  starts with element 0, and integer arrays take up 2/5ths of the
space of floating point arrays.

More  than  one  array  can  be  dimensioned  in  a  DIM  statement by
separating  the  arrays  by  commas.  If  the  program  executes a DIM
statement for any array more than once, the message 'REDIM'D ARRAY' is
reported.  It  is  good  programming  practice to place DIM statements
near the beginning of the program.

           10 DIM A$(40),B7(15),CC%(4,4,4)
                     |      |         |
           41 elements   16 elements  125 elements


DIRECTORY -- List the files of a diskette
DIR

        DIRECTORY ["filespec"] [,R] [,Ddrive] [<ON|,>Udevice]

A  directory  is  a  list  of  the  names  of  the files that are on a
diskette.  The directory listing consists of the name of the diskette,
the  names,  sizes,  and filetypes of all the files on a diskette, and
the  remaining  free  space  on  the diskette. The filespec is used to
specify  a pattern  match string to view selected files.  Not all disk
drives support the same options or filespecs; refer to your DOS manual
for details. The C64DX allows you to print DIR listings without having
to 'load' the directory; see example below.

The commands DIR, DIRECTORY, and CATALOG have the exact same function.
They can be used in direct or program mode.

      DIRECTORY               List all files on the diskette
                              in the default system drive
      DIR "*.src", U9         Lists the all the files ending with
                              ".src" on unit 9.
      DIR "*,=p",R            List all the deleted but recoverable
                              PRG-type files on the system drive.

   OPEN 4,4:CMD 4:DIR:CLOSE 4   Print DIR listing to printer unit 4.

The following program can be used to load the directory into variables
for use within a program. In this case, the filename is simply printed
to the screen:

    10 OPEN 1,8,0,"$0:*,P,R"                open dir as a file
    20 : IF DS THEN PRINT DS$: GOTO 100     abort if error
    30 GET#1,X$,X$                          trash load address
    40 DO                                   read each line
    50 : GET#1,X$,X$: IF ST THEN EXIT       trash links, check EOF
    60 : GET#1,BL$,BH$                      get file size
    70 : LINE INPUT#1, F$                   get filename & type
    80 : PRINT LEFT$(F$,18)                 print filename
    90 LOOP                                 loop until EOF
   100 CLOSE 1                              close dir


DISK -- Send a disk command

                DISK "command_string" [<ON|,>Udevice]

The  DISK  command is used to send special commands to the DOS via the
disk  drive's  command  channel.  The DISK command is analogous to the
following BASIC code:

            OPEN 1,n,15: PRINT#1,"command_string": CLOSE 1

Not  all  disk drives understand the same commands.  Refer to your DOS
manual  for commands and command syntax for your drive.  Note that the
drive number, if any, must be included in the command_string.

        DISK "U0>10"          Renumber system drive to 10.
        DISR "U0>V"+chr$[0)   Turn off write verify
        DISK "S0:file",U(n)   Scratch "file" on unit n


DLOAD -- Load a BASIC program file from disk

              DLOAD "filename" [,Ddrive] [<ON|,>Udevice]

This  command  copies a BASIC program from disk into the BASIC program
area of the computer. It can then be edited, DSAVEd, or RUN.

Used  in  program mode,  it overlays the current program in memory and
begin  execution  automatically  at the first line of the new program.
Variable definitions will be left intact,  but any open data files and
the disk command channel will be automatically closed.  This is called
CHAINING.

See also RUN. Use BLOAD to load binary or machine language data.

     DLOAD "myprogram"      Searches the default system disk drive
                            for the BASIC program "myprogram",
                            loads it, and relinks it.
     DLOAD (F$),U9          LOADs a program whose name is in F$
                            from disk unit 9.


DMA -- Perform a DMA operation

DMA command [,length,source(l/h/b),dest(l/h/b),subcmd,mod(l/h) [,...]]

             [*** THIS COMMAND IS SUBJECT TO CHANGE ***]

The DMA command defines and executes a Direct Memory Access operation.
The parameters are used to construct a DMA list,  which is then passed
to   the   DMA   processor  for  execution.  Refer  to  the  DMA  chip
specification for details.  Chained DMA commands are not allowed,  but
multiple  DMA  commands  can  be given and the DMA handler will set up
and execute each one, one at a time. Refer to the system memory map to
find out where things are.

Because  this  command  directly  accesses system memory, extreme care
should  be  taken in its use.  Changing the wrong memory locations can
crash the computer (press the reset button to reboot).

 DMA 3, 2000, ASC("+"), 0, DEC("800"), 0        Fill screen with '+'
 DMA 0, 2000, DEC("800"), 0, DEC("8000"), 1     Copy screen to $18000


DMODE -- Set graphic display mode

         DMODE jam, comp, inverse, stencil, style, thickness

             [*** THIS COMMAND IS SUBJECT TO CHANGE ***]

                   jam                     0-1
                   complement              0-1
                   inverse                 0-1
                   stencil                 0-1
                   style                   0-3
                   thickness               1-8


DO/LOOP/WHILE/UNTIL/EXIT -- Program loop definition and control

      DO   [UNTIL boolean_expression | WHILE boolean_expression]
                 .
                 .         statements [EXIT]
                 .
      LOOP [UNTIL boolean_expression | WHILE boolean_expression]

Performs  the  statements  between  the  DO  statement  and  the  LOOP
statement.  If  no  UNTIL  or WHILE modifies either the DO or the LOOP
statement,   execution   of   the   intervening  statements  continues
indefinitely.  If an EXIT statement is encountered in the body of a DO
loop,  execution  is  transferred to the first statement following the
nearest  LOOP  statement.  Do loops may be nested, following the rules
defined for FOR-NEXT loops. If the UNTIL parameter is used the program
continues  looping  until  the boolean argument is satisfied  (becomes
true).  The  WHILE  parameter  is  basically the opposite of the UNTIL
parameter:  the  program  continues  looping  as  long  as the boolean
argument is TRUE. An example of a boolean argument is A=1, or G>65.

  DO UNTIL X=0 or X=1                        This loop will continue
          : statements                       until X=0 or X=1. If
  LOOP                                       X=0 or 1 at beginning
                                             the loop won't execute.

  10 A$="": DO GETKEY A$: LOOP UNTIL A$="Q"  This will loop until
                                             the user types 'Q'

  10 DOPEN#1,"FILE"                              This program will
  20 C=0                                         count the number of
  30 DO: LINEINPUT#1,A$: C=C+1: LOOP UNTIL ST    lines in FILE
  40 DCLOSE#1
  50 PRINT"FILE CONTAINS";C;" LINES."


DOPEN -- Open a disk file

DOPEN#lf,"filename[,<S|P>]"[,L[reclen]] [,W] [,Ddrive] [<ON|,>Udevice]

This  command  OPENs  a file on disk for reading or writing. If is the
logical  file  number,  which  you will use in PRINT#,  INPUT#,  GET#,
RECORD#,  and  DCLOSE# commands to reference the channel to your file.
The  filename is required.  The defaults are to OPEN a SEQuential file
for  Reading,  in which case the file must exist or a 'FILE NOT FOUND'
error results.  To  create  an  file and write to it,  use the 'W'rite
option.  'FILE  EXISTS'  error  is  report  if  an output file already
exists. To read or write a RELative file, use the 'L'ength option. The
'reclen' record length is required only when creating a relative file.
For  more information regarding Relative files, see the RECORD command
and refer to your DOS manual. See also APPEND.

See the OPEN command for a discussion about channel and device
numbers.

DOPEN#1,"readfile"     Opens sequential READFILE for reading.
DOPEN#1,"writefile",W  Creates & opens seq WRITEFILE for writing.
DOPEN#1,"file,P",U(u)  Opens a PRoGram type file for reading on unit U
DOPEN#1,(rf$),L        Open existing relative file whose name's in RF$
DOPEN#a,"rel",L80      Create a relative file with record length of 80


DPAT -- Set graphic draw pattern

           DPAT type [, # bytes, byte1, byte2, byte3, byte4]

             [*** THIS COMMAND IS SUBJECT TO CHANGE ***]

                type                    0-63
                # bytes                 1-4
                byte1                   0-255
                byte2                   0-255
                byte3                   0-255
                byte4                   0-255


DSAVE -- Save a BASIC program into a disk file

            DSAVE "[@]filename" [,Ddrive] [<ON|,>Udevice]

This  command  copies  a  BASIC program in the computer's BASIC memory
area  into a PRoGram-type disk file.  If the file already exists,  the
program is NOT stored and the error message 'FILE EXISTS' is reported.
If  the  filename  is preceded with an '@', then if the file exists it
will  be  replaced  by the program in memory. Because of some problems
with the  'save-with-replace' option on older disk drives,  using this
option  is not recommended if you do not know what disk drive is being
used.  Use the DVERIFY to compare the program in memory with a program
on disk.

To save a binary program, use the BSAVE command.

    DSAVE "myprogram"       Creates the PRG-type file MYPROGRAM
                            on the default system disk and copies
                            the BASIC program in memory into it.

    DSAVE "@myprogram"      Replaces the PRG-type file MYPROGRAM
                            with a new version of MYPROGRAM. If
                            MYPROGRAM doesn't exist, it's created.

    DSAVE (F$),U9           Saves a program whose name is in F$
                            on disk unit 9.


DVERIFY -- Compare a program in memory with one on disk

             DVERIFY "filename" [,Ddrive] [<ON|,>Udevice]

This  command  is  just like a DLOAD, but instead of LOADing the BASIC
program  file  into  computer  memory  the  data is read from disk and
compared  to  computer  memory.  If  there's  any  difference at all a
'VERIFY ERROR' is reported.

Note:  If  the  BASIC  program  in  memory  is not located at the same
address  as  the  version  on  disk was SAVEd from, the files will not
match even if the program is otherwise identical.  The comparison ends
when the last byte is read from the disk file.

Use the BVERIFY command to compare memory with binary files.

                         DVERIFY "myprogram"


Good:   SEARCHING FOR 0:myprogram     Bad:   SEARCHING FOR 0:myprogram
        VERIFYING                            VERIFYING
        OK                                   ?VERIFY ERROR


ELLIPSE -- Draw an ellipse on a graphic screen

       ELLIPSE x_center, y_center, x_radius, y_radius [,solid]

The ELLIPSE command will draw an ellipse with the given radii centered
at (x_center,y_center) on the current graphic screen. The ellipse will
be filled (i.e., a disc) if SOLID is non-zero.

                        ELLIPSE 160,100,65,50

The  above  example  will  draw  an ellipse in the center of a 320x200
pixel screen  (160,100)  having radii of  (65,50)  pixels.  The aspect
ratio of the screen may cause it to appear as an circle, however.  See
also the CIRCLE command.


ELSE -- See IF/THEN/ELSE


END -- Define the end of program execution

                                 END

The  END  statement  terminates  program execution.  It does not close
channels  or  files,  and it does not clear any variables or reset any
pointers. An END statement does not need to be put at the last line of
a program.

The  CONTinue  command  can  be used to resume execution with the next
statement following the END statement. See also the STOP command.


ENVELOPE -- Define musical instrument envelopes

    ENVELOPE n, [,[atk] [,[dec] [,[sus] [,[rel] [,[wf] [,pw] ]]]]]

                 n............... Envelope number        (0-9)
                 atk ............ Attack rate            (0-15)
                 dec ............ Decay rate             (0-15)
                 sus ............ Sustain rate           (0-15)
                 rel ............ Release rate           (0-15)
                 wf ............. Waveform:   0 = triangle
                                              1 = sawtooth
                                              2 = pulse (square)
                                              3 = noise
                                              4 = ring modulation
                 pw ............. Pulse width            (0-4095)

             [*** THIS COMMAND IS SUBJECT TO CHANGE ***]

A parameter that is not specified will retain its current value. Pulse
width  applies  to  pulse  waves  (wf=2) only and is determined by the
formula (pwout = pw/40.95 %), so that pw = 2048 produces a square wave
and  values  of  0  or  4095  produce  constant  DC output.  The C64DX
initializes the ten (10) tune envelopes to:

                     n  A  D  S  R  wf  pw           instrument
                     ------------------              -------------
         ENVELOPE    0, 0, 9, 0, 0, 2, 1536           piano
         ENVELOPE    1,12, 0,12, 0, 1                 accordion
         ENVELOPE    2, 0, 0,15, 0, 0                 calliope
         ENVELOPE    3, 0, 5, 5, 0, 3                 drum
         ENVELOPE    4, 9, 4, 4, 0, 0                 flute
         ENVELOPE    5, 0, 9, 2, 1, 1                 guitar
         ENVELOPE    6, 0, 9, 0, 0, 2, 512            harpsichord
         ENVELOPE    7, 0, 9, 9, 0, 2, 2048           organ
         ENVELOPE    8, 8, 9, 4, 1, 2, 512            trumpet
         ENVELOPE    9, 0, 9, 0, 0, 0                 xylophone


ERASE -- Delete disk files

           ERASE "filespec" [,Ddrive] [<ON|,>Udevice] [,R]

This  command  is  identical  to  DELETE  and SCRATCH. See the SCRATCH
command for details.

     ERASE "myfile" Deletes the file MYFILE on the system drive.


ERR$ -- Error message function

                         ERR$ (error_number)

This  function  returns  a  string  which  is  the BASIC error message
corresponding  to the given error_message.  If the given number is too
small  (less  than  1)  or  too  large  (greater  than 41) an 'ILLEGAL
QUANTITY' error is reported.

This  function is usually used to display a BASIC error condition in a
TRAP  routine,  using  the  BASIC  error  word ER as the error_number.
Note that when ER=-1, no BASIC error has occurred and ERR$(-1) results
in an 'ILLEGAL QUANTITY' error.

See the example at TRAP.


EXIT -- See DO/LOOP/WHILE/UNTIL/EXIT


EXP -- Function to return e^x

                             EXP (number)

This function returns the numeric value of e (2.71828183), the base of
natural  logarithms)  raised  to  the  power  of  given number. If the
number is greater than 88.0296919 an 'OVERFLOW' error is reported.

                X = EXP(4)              Result is X=54.5981501


FAST -- Set system speed to 3.58MHz

FAST is the default state of the system.  FAST is used to restore this
state  following  direct  access of "slow" I/O devices such as the SID
sound chips.


FETCH -- (see the DMA command)


FILTER -- Define sound filter parameters

            FILTER [freq] [,[lp] [,[bp] [,[hp] [,res] ]]]

            freq ..... Filter cut-off frequency (0-2047)
            lp ....... Low pass filter on (1) off (0)
            bp ....... Band pass filter on (1), off(0)
            hp ....... High pass filter on (1), off(0)
            res ...... Resonance (0-15)

             [*** THIS COMMAND IS SUBJECT TO CHANGE ***]

Unspecified  parameters  result in no change to the current value. The
filter  output  modes  are  additive.  For  example,  how low pass and
high  pass filters can be selected to produce a notch (or band reject)
filter  response.  For  the  filter to have an audible effect at least
one filter output mode must be selected and at least one voice must be
routed through the filter.


FIND -- Find text in a BASIC program.

                     FIND :string: [,line_range]
                     FIND "string" [,line_range]

This  is  a direct (edit) mode command. FIND looks for all occurrences
of  string  in  the  program and displays each line containing string,
with string highlighted.  Use the <C=> key to slow the display, or the
<NO-SCROLL> key to pause the display. Press <STOP> to cancel.

Any character can be used for the string delimiter, but there are side
effects.  Using  a  non-quote  delimiter  will  cause the string to be
tokenized,  and  FIND  will find only tokenized strings in the program
that  match.  Using  a quote character as the delimiter will cause the
string to be interpreted as plain PETSCII,  and any matches found will
therefore  be  plain  PETSCII.  Searching for some tokens such as DATA
statements  may  require  the  use  of colons as delimiters due to the
special affect these commands have upon the interpreter.

If  the  line  number range is not given  (see LIST for description of
range parameter), the entire program is searched.


FN xx -- User defined function

                          FN xx (expression)

The result of this numeric function is determined by the BASIC program
in a DEF FN statement. See the example at DEF FN.


FOR/TO/STEP/NEXT -- Program loop definition and control

              FOR index = start TO end [STEP increment]
               |
              NEXT index [,index]

This command group performs a series of instructions a given number of
times.  The  loop  index  is  a  floating point (non-integer) variable
which  will  initially be set to the start value and be incremented by
the  STEP increment  when the NEXT statement is encountered.  The loop
continues until the index exceeds the end value at the NEXT statement.

The  start,  end,  and  increment  values  can be numeric variables or
expressions.  If the STEP increment is not specified, it is assumed to
be one (1).  The STEP increment can be any value,  positive, negative,
or non-integer.  If the STEP increment is negative, the loop continues
until the index is less than the end value at the NEXT statement.

Note that, regardless of the start, end, or increment values, the loop
will  always  execute at least once.  The index can be modified within
the loop, but it is bad practice to do so.  It is also bad practice to
GOTO  a  line  inside a loop structure,  or to similarly jump out of a
loop structure (which can cause an 'OUT OF MEMORY' error).

Loops may be nested.  If too many are nested, an 'OUT OF MEMORY' error
is reported (depends upon stack size, room for about 28 nested loops).

The  index  variable can be omitted from the NEXT statement,  in which
case  the NEXT will apply to the most recent FOR statement.  If a NEXT
statement is encountered and there is no preceding FOR statement, the
error 'NEXT WITHOUT FOR' is reported.

                      10 FOR L = 1 TO 10
                      20 PRINT L
                      30 NEXT L
                      40 PRINT "I'M DONE! L = "L

This  program  prints  the  numbers  from one to ten,  followed by the
message I'M DONE! L = 11.

                      10 FOR L = 1 TO 100
                      20 FOR A = 5 TO 11 STEP .5
                      30 NEXT A
                      40 NEXT L

This program illustrates a nested loop.


FOREGROUND -- Set the text color of the display

                           FOREGROUND color

Sets  the  text  color to the given color index.  Color must be in the
range  (0-15).  See  the Color Table.  COLOR must be ON (see the COLOR
command).


FRE -- Free byte function

                               FRE (x)

This  function  returns  the  number  of available ("free") bytes in a
specified area.

  PRINT FRE(0)  Shows the amount of memory left in the program area,
                C64DX bank 0

  X = FRE(1)    X= the amount of available memory in variable area
                C64DX bank 1. This causes a "garbage collect" to
                occur, a process which compacts the string area.

  X = FRE(2)    X= the number of expansion RAM banks present.


GCOPY -- Copy a graphic area

                    [*** NOT YET IMPLEMENTED ***]


GENLOCK -- Enable or disable video sync mode & colors

                    GENLOCK ON  [,color#]...
                    GENLOCK OFF [,color#,R,G,B]...

To  enable  video sync mode and specify which colors are affected, use
the  GENLOCK  ON  command,  and list the palette color indices (0-255)
which will display external video.

To  disable  video sync mode and restore the associated palette colors
use  the  GENLOCK  OFF  command,  and list the color index and its RGB
values to restore them (see the SET PALETTE command for details). Also
see the PALETTE RESTORE command.


GET -- Get input data from the keyboard

                          GET variable_list

The GET statement is a way to get data from the keyboard one character
at  a time.  When the GET is executed, the character that was typed is
received.  If no character was typed, then a null (empty) character is
returned,  and the program continues without waiting for a key.  There
is  no need to hit the <RETURN> key,  and in fact the <RETURN> key can
be received  with  a GET.  The word GET is followed by a variable name,
usually  a  string  variable. If a numeric were used and any key other
than  a number was hit,  the program would stop with an error message.
The  GET statement may also be put into a loop,  checking for an empty
result,  that  waits  for  a key to be struck to continue.  The GETKEY
statement could also be used in this case.  This statement can only be
executed within a program.

                  10 DO: GET A$: LOOP UNTIL A$ ="A"

       This line waits for the A key to be pressed to continue.


GETKEY -- Get input character from keyboard (wait for key)

                         GETKEY variable_list

The GETKEY statement is very similar to the GET statement.  Unlike the
GET  statement,  GETKEY  waits for the user to type a character on the
keyboard.  This  lets it be used easily to wait for a single character
to be typed. This statement can only be executed within a program.

                             10 GETKEY A$

This  line  waits for a key to be struck. Typing any key will continue
the program.


GET# -- Get input data from a channel (file)

              GET# logical_channel_number, variable_list

Used with a previously OPENed device or file to input one character at
a time. Otherwise, it works like the GET statement. This statement can
only executed within a program.

                             10 GET#1,A$


GO64 -- Exit C64DX mode and switch to C64 mode

                                 GO64

This statement switches from C64DX mode to C64 mode. The question 'ARE
YOU SURE?' (in direct mode only) is posted for the user to respond to.
If Y and return is typed then the currently loaded program is lost and
control  is  given  to C64 mode.  This statement can be used in direct
mode or within a program.


GOSUB -- Call a BASIC subroutine

                              GOSUB line

This  statement  is  like the GOTO statement, except that the computer
remembers  from where it came.  When a line with a RETURN statement is
encountered,  the  program  jumps  back  to  the statement immediately
following  the  GOSUB.  The  target  of  a GOSUB statement is called a
subroutine.  A  subroutine  is  useful  if  there  is a section of the
program  that  can  be used by several different parts of the program.
Instead of duplicating the section over and over,  it can be set up as
a subroutine and called with a GOSUB statement from different parts of
the  program.  This  also make the main part of your program much more
readable. See also the RETURN statement.

Variables  are  shared with the main program and all subroutines.  You
can  pass information to,  and get information back from,  subroutines
by using variables as messengers.

GOSUB  statements  can  be  nested.  That is,  one subroutine can call
another  subroutine,  and  the  computer  automatically keeps track of
all  the calls.  It's important not to jump into or out of subroutines
since  this  can  confuse the computer.  If too many GOSUBs are nested
(usually  cause  by  jumping  out of them) an 'OUT OF MEMORY' error is
reported  because  the  computer  ran out of room to keep track of all
the calls.

     10 DIR : GOSUB 100              show directory, check status
     20 GOSUB 200                    print gap
     30 LIST "PROGRAM": GOSUB 100    show listing, check status
     40 GOSUB 200                    print gap
     50  etc...
     90 END
     99 :
    100 REM SUBROUTINE TO CHECK DISK STATUS
    110 IF DS THEN GOSUB 200: PRINT "DISK ERROR: ";DS$
    120 RETURN
    199 :
    200 REM SUBROUTINE TO PRINT A SPACER ON THE SCREEN
    210 PRINT
    220 FOR I=1 TO 39: PRINT"-";: NEXT
    230 PRINT
    240 RETURN


GOTO -- Transfer program execution to specified line number

                          GOTO  line_number
                          GO TO line_number

After a GOTO statement is executed,  the next line to be executed will
be the one with the line number following the word GOTO.  When used in
direct  mode,  GOTO  line  number  allows starting of execution of the
program at the given line number without clearing the variables.

                         10 PRINT"COMMODORE"
                         20 GOTO 10

The  GOTO  in  line 20 makes line 10 repeat continuously until STOP is
pressed.


GRAPHIC -- select graphic mode

                       GRAPHIC CLR
                       GRAPHIC command# [,args]

Basically this is a modified C64-type SYS command,  minus the address.
In  the  C64DX system,  this will represent the ML interface,  not the
BASIC 10.0 interface which is implemented in the development system.

             [*** THIS COMMAND IS SUBJECT TO CHANGE ***]

GRAPHIC CLR  initializes  (warm-starts)  the BASIC graphic system.  It
clears any existing graphic modes, screens, etc.  and allows a program
to commence graphic operations from scratch.


HEADER -- Format a diskette

          HEADER "diskname" [,Iid] [,Ddrive] [<ON|,>Udevice]

The  HEADER  command prepares a new diskette for use, sometimes called
FORMATting a diskette. There are two types of "newing" a diskette -- a
long form and a quick (or short) form. You must use the long form when
preparing a new diskette for its first use. Thereafter you can use the
quick form.

WARNING:  Formatting  a  diskette  (long  or  short)  will destroy all
existing  data  on  the  diskette!  In  direct  mode, you are asked to
confirm  what  you are doing with 'ARE YOU SURE?'.  Type 'Y' and press
return  to  proceed,  or  TYPE ANY OTHER CHARACTER AND PRESS RETURN TO
CANCEL the command. In program mode there is no confirmation prompt.

The long HEADER form requires a diskname and an ID.  The diskette will
be  completely  (re)sectored,  zeros  written to all blocks, and a new
system track (directory, BAM, etc.) will be created.

        HEADER "newdisk",I01            prepares a new diskette

The short HEADER form is performed when the ID option is omitted.  The
diskette is assumed to have been previously formatted,  and only a new
system track  (directory,  BAM,  etc.)  is installed.  This is roughly
equivalent to deleteing all the files, but much quicker.

        HEADER "makelikenew"            re-news an working diskette

The  diskname  is  limited  to  16 characters and the ID string to two
characters.  The  same rules apply for the diskname as for a filename.
Some  Disk  Systems  use  the  ID string to tell if you have swapped a
diskette in a drive,  so it's recommended that the ID string be unique
for each of your diskettes. Some more examples:

                   HEADER "QUICK"
                   HEADER "MYDISK", I23
                   HEADER "RECS", I"FB", U9
                   HEADER (FILES), I(ID$), U(UNIT)


HELP -- Show the BASIC line that cause the last error

                                 HELP

The  HELP  command  is  used  after  an  error  has been reported in a
program.  When  HELP  is  typed,  the  line  where  the error occurred
listed,  with  the  portion  containing  the error highlighted.  Print
ERR$(ER)  for  the  error  message,  and  print EN or EL for the error
number and error line,  respectively.  HELP can be used in direct mode
or in program mode.  Note that,  in the case of many I/O errors, there
is no associated BASIC error. Check ST or DS$ errors in these cases.


HEX$ -- Hexadecimal value function

                      HEX$ (decimal_expression)

This  function  returns  a  4-character  string  that  represents  the
hexadecimal  value  of the numeric decimal expression.  The expression
must  be  in  the  range  (0-65535,  $0000-$FFFF  hex)  or an 'ILLEGAL
QUANTITY' error is reported.

     PRINT HEX$(10)                The string "000A" is printed.
     PRINT RIGHT$(HEX$(10),2)      The string   "0A" is printed.


HIGHLIGHT -- Set the text highlight color of the display

                           HIGHLIGHT color

Sets  the  highlight  color to the given color index.  The color value
must  be  in the range (0-15).  See the Color Table.  COLOR must be ON
(see the COLOR command).  The highlight color is used in HELP messages
and FIND/CHANGE strings.


IF/THEN/GOTO/ELSE -- Conditional program execution

   IF expression <GOTO line | THEN then_clause> [:ELSE else_clause]

IF...THEN  lets the computer analyze a BASIC expression preceded by IF
and  take one of two possible courses of action.  If the expression is
true, the statement following THEN is executed. This expression can be
any  BASIC  statement.  If  the expression is false,  the program goes
directly to the next line, unless an ELSE clause is present.  The ELSE
clause, if present, must be in the same line as the IF-THEN part. When
an  ELSE clause is present,  it is executed when the THEN clause isn't
executed. In other words, the ELSE clause executes when the expression
is  FALSE.  See BEGIN/BEND to spread the IF statement out over several
lines.  An  ELSE statement is matched to the closest THEN statement in
the case of nested IF/THEN statements.

The expression being evaluated may be a variable or formula,  in which
case  it  is  considered true if nonzero,  and false if zero.  Usually
expressions involve relational operators =, <, >, <=, >=, <>.

            50 IF X>0 THEN PRINT "X>0": ELSE PRINT "X<=0"

If  X  is  greater  than 0, the THEN clause is executed,  and the ELSE
clause  isn't.  If  X  is  less than or equal to 0, the ELSE clause is
executed and the THEN clause isn't.


INPUT -- Get input from the keyboard

              [LINE] INPUT ["prompt"<,l;>] variable_list

The INPUT statement pauses the BASIC program, prints the prompt string
if present,  prints a question mark and a space, and waits for data to
be typed by the user, terminated by a return character.  If the prompt
string  ends with a comma instead of a semicolon,  a question mark and
space is not printed.

Input is gathered and assigned to variables in the variable_list.  The
type  of  variable  must  match  the  type  of  input typed or a 'TYPE
MISMATCH'  error  is  reported.  Separate data items typed by the user
must  be  separated  with commas.  String data with imbedded spaces or
commas must be surrounded with quotes.  If insufficent data to satisfy
the  variable-list  is  typed, two question marks are displayed by the
computer  to  prompt for additional data to be input.  If the computer
does  not  understand  the input (such as the user typing cursor up or
down keys)  the computer responds with the message  'REDO FROM START?'
and  waits  for acceptable data to be entered. Input is limited to 160
characters (two screen lines in 80-column mode),  which is the size of
the input buffer.

The INPUT statement can only be executed from within a program.

LINE  INPUT  allows  the  program to input a string which includes any
PETSCII  character  (including  colons, commas, imbedded spaces, etc.)
up  to  but not including a null or return character.  There should be
only  one string-type variable name in the variable_list in this case,
but  if there are more the computer prompts as usual with two question
marks for more data to assign to the additional variables.

     10 INPUT "WHAT'S YOUR FIRST NAME AND AGE"; NA$,A
     20 PRINT "YOUR NAME IS ";NAS;" AND YOU ARE";A;" YEARS OLD"

The above INPUT is the traditional BASIC form.

     10 LINE INPUT "WHAT'S YOUR ADDRESS"; AD$
     20 PRINT "YOUR ADDRESS IS: ";AD$

The  above  INPUT  allows  an  entire line of data to be assigned to a
string variable, including commas and other common punctuation marks.

     10 INPUT "ENTER YOUR NAME HERE: ", NA$

The  above  INPUT  suppresses  the  traditional '? ' prompt by using a
comma instead of a semicolon after the prompt string.  To suppress the
'?' without a prompt string, make the prompt string null.


INPUT# -- Input data from an I/O channel (file)

          [LINE] INPUT#logical_channel_number, variable_list

The  INPUT#  command  works  like  the INPUT command, except no prompt
string  is  allowed  and  input  is  gathered from a previously OPENed
channel or file. This command can only be used in a program.

The logical channel number is the number assigned to the device (file)
in an OPEN (or DOPEN) statement. Items in the variable list must agree
with the type of data input, or a 'FILE DATA ERROR' will resuit.

On  the  C64DX,  an End Of File (EOF) condition or bad I/O status will
terminate  input,  as  if  a return character was received.  It's good
practice  to  examine  the I/O status byte (and the DS disk status for
file I/O) after every I/O instruction to check for problems or errors.

  10 DOPEN#1, "FILE"                             This program will
  20 C=0                                         count the number of
  30 DO: LINE INPUT#1,AS: C=C+1: LOOP UNTIL ST   lines in FILE
  40 DCLOSE#1
  50 PRINT"FILE CONTAINS";C;" LINES."


INSTR -- Get the location of one string inside another string

           INSTR (string_1, string_2 [,starting_position])

This  function  searches  for  the  first  occurrence  of  string_2 in
string_1 and returns its location.  A value of zero (0) is returned if
no match is found,  if either string is null (empty),  or if  string_2
is longer than string_1.

If the starting position is given, the search begins at that location,
otherwise the search begins at the first character of string_1.

The strings can be literals, variables, or string expressions.

        X = INSTR("123456","4")         Result is X=  0
        X = INSTR("123456","X")         Result is X= -1
        X = INSTR("123123","2")         Result is X= 123
        X = INSTR("123123","2",3)       Result is X=-124


INT -- Greatest integer function

                           INT (expression)

This  function returns the greatest integer less than or equal to the
numeric expression.


JOY -- Joystick function

                              JOY (port)

This  function  returns  the  state  of  a  joystick controller in the
specified port.

        When port=l returns position of joystick 1
        When port=2 returns position of joystick 2

The value returned is encoded as follows:

       Fire = 128 +                  1

                               8           2

                          7          0          3

                               6           4

                                     5

A value of zero  (0) means that the joystick is not being manipulated.
A  value of  128  or more means that the fire button is being pressed.
The possible vales returned are:

       0     No activity             128     fire
       1     up                      129     fire + up
       2     up + right              130     fire + up + right
       3     right                   131     fire + right
       4     right + down            132     fire + right + down
       5     down                    133     fire + down
       6     down + left             134     fire + down + left
       7     left                    135     fire + left
       8     left + up               136     fire + left + up


KEY -- Enable, disable, display, or define function keys

                          KEY ON
                          KEY OFF
                          KEY [key#, string]

There are 14 function keys available on the C64DX (seven unshifted and
seven  shifted).  The  user  can  assign  a string consisting of BASIC
commands, control codes, escape functions, or a combination of each to
function key. The data assigned to a key is typed out when that key is
pressed,  just  as  if  the  characters  were  typed one by one on the
keyboard.  The user can enable ("turn on") or disable ("turn off") the
function keys.  When they are disabled, pressing a function key return
that key's normal character code instead of the string assigned to it.
This includes the HELP and (shifted) RUN keys.  It is also possible to
redefine the HELP and (shifted) RUN keys,  as function keys 15 and 16,
respectively.  The  system  has  default  assignments for all function
keys.  KEY  with  no  parameters  displays  a  listing  of the current
assignments for all the function keys.

The maximum length for all the definitions together is 240 characters.
If an assignment would be too big to fit,  an 'OUT OF MEMORY' error is
reported and the assignment is not made.

            KEY 2, "DIR U9"+CHR$(13)

This  causes  the  computer to display the directory from disk unit #9
when function key 2 is pressed.  This is equivalent to typing 'DIR U9'
and pressing the <RETURN> key directly.  The CHR$(13) is the character
for  <RETURN>.  Other  often  used  control  codes  are  CHR$(141) for
'shifted RETURN', CHR$(27) for 'ESCape', and CHR$(34) to incorporate a
double quote into a KEY string.

            KEY 2, "DIR"+CHR$(34)+"*=P"+CHR$(34)+CHR$(13)

This  is  equivalent  to  typing DIR"*=P" and pressing <RETURN> at the
keyboard.   Note   the   way   quotes  can  be  incorporated  into  an
assignment. When function key 2 is pressed, a directory of all program
files on the default system disk will be displayed.

            KEY OFF

This turns off function key strings. Pressing a function key now would
return the character codes associated with F-keys as on the VIC-20 and
C64 computers.  KEY ON would re-enable function key strings, unchanged
from  their  previous  assignments.  To  restore  the  system  default
assignments, reset the computer.


LEFT$ -- Get the leftmost characters of a string

                         LEFT$ (string,count)

This  function returns a string containing the leftmost 'count' number
of   characters   of  the  string  expression.  Count  is  an  numeric
expression  in the range (0-255).  If count is greater than the length
of the string,  the entire string will be returned.  If count is zero,
a null (empty) string will be returned.

          A$ = LEFT$("123ABC",3)          Result is A$="123"


LEN -- Get the length of a string

                             LEN (string)

This function returns the number of characters in a string expression.
Nonprinting characters and blanks are counted.

        A = LEN("ABC")                  Result is A=3


LET -- Assign a value to a variable

                     [LET] variable = expression

The  LET  command  is  optional,  since  the  equal  sign by itself is
understood  by  the computer to mean assignment.  Multiple assignments
on LET statements are not allowed.

          10 LET A=1: LET B=A+1: LET C$=" THREE"
          20 :   D=1:     E=D+1:     F$=" THREE"
          30 PRINT A;B;C$
          40 PRINT D;E;F$

        Output:         1 2 THREE
                        1 2 THREE

LINE -- Draw a line on a graphic screen

                         LINE x0, y0, x1, y1

LINE  draws  a  line  on the currently defined graphic screen with the
currently  defined  draw  modes.  The  line  is  draw  from (x0,y0) to
(x1,y1).


LIST -- List a BASIC program from memory or disk

                   LIST [startline] [- [endline] ]

               LIST "filename" [,Ddrive] [<,|ON>Udevice]

LIST  is  used to view part or all of a BASIC program in memory or all
of  a  BASIC  program  on disk  (without affecting the program that is
currently in memory).

The  display can be slowed down by holding down the <C=> key or it can
be paused  by pressing the <NO-SCROLL> key or <CONTROL><S>.  A listing
that is paused  can  be  restarted by pressing <NO-SCROLL> again or by
pressing <CONTROL><Q>. The display can be stopped by pressing <STOP>.

If the word LIST is followed by a line number, the computer shows only
that  line  number.  If  LIST is typed with two numbers separated by a
dash,  the  computer shows all lines from the first to the second line
number.  If  LIST  is  typed followed by a number and just a dash,  it
shows  all  lines from  that number to the end of the program.  And if
LIST is typed, a dash, and then a number, all lines from the beginning
of  the  program  to  that  line  number  are  LISTed.  By using these
variations, any portion of a program can be examined or easily brought
to the screen for modification.  LIST can be used in direct mode or in
a BASIC program.

    LIST         Shows entire program.
    LIST 100-    Shows from line 100 until the end of the program.
    LIST 10      Shows only line 10.
    LIST -100    Shows lines from the beginning until line 100.
    LIST 10-200  Shows lines from 10 to 200, inclusive.


LOAD -- Load a program or data into memory from disk

          LOAD "filename" [,device_number [,relocate_flag]]

This  command  loads  a file into the computer's memory.  The filename
must be given,  and pattern matching may be used.  In the case of dual
drive  systems,  the  drive number must be part of the filename.  If a
device number is given, the file is sought on that unit, which must be
a  disk  drive.  If  a device number is not given,  the default system
drive is used. See also DLOAD and RUN commands.

The  relocate_flag is used to LOAD binary files.  If the relocate_flag
is present and non-zero,  the file will be copied into memory starting
at the address stored on disk when the file was SAVEd.  See BLOAD.  Do
not  use  the  relocate_flag  to  load  BASIC  programs:  they will be
automatically  relocated  to  the  start of the BASIC program area and
relinked.

To  compare  a  program  in  memory  to a disk file, use the VERIFY or
DVERIFY command. To compare a binary file, use BVERIFY.

See the discussion at DLOAD regarding CHAINING programs.

  LOAD "PROG"        Loads BASIC program PROG from the system drive.
  LOAD FILE$,DRV     Loads a program whose name is in the variable
                     called F$ from the unit whose number is in DRV.
  LOAD "0:PROG" 8    Loads BASIC program PROG from unit 8, drive 0.
  LOAD "BIN",8,1     Loads a binary file into memory.


LOCATE -- [*** NOT YET IMPLEMENTED ***]


LOG -- Get the natural logarithm of a number

                         LOG (number)

This function returns the natural logarithm of a numeric expression. A
natural log is a log to the base e (2.71828183). See the EXP function.
To convert to log base 10, divide by LOG(10).

        A = LOG(123)                   Result is A=4.81218436
        A = LOG(123) / LOG(10)         Result is A=2.08990511


LOOP -- See DO/LOOP/WHILE/UNTIL/EXIT


LPEN -- Get the position of a lightpen

                            PEN (position)

This  function  returns  the  current  position  of  a lightpen on the
screen.  When  position=0,  the  X  position  is  returned,  and  when
position=1 the Y position is returned. Note that lightpen coordinates,
like sprite coordinates, are offset from the normal graphic coordinate
map.  This  means  you  have  to  calculate where the lightpen is with
respect  to the screen display.  The electronics of each lightpen also
introduces a skew which must be factored into your calculations.

The  X resolution is limited to every 2 pixels,  and will always be an
even  number  in the approximate range (60-320).  The Y position is in
the approximate range  (50-250).  If either the X or the Y position is
zero, the lightpen is off-screen.

Note  that  a  lightpen  COLLISION need not be enabled to use LPEN.  A
bright  background  color,  such  as  white,  is  usually  required to
stimulate the light pen. Lightpens only work in game port 1.

      10 TRAP 40                        We're done if STOP key
      15 BACKGROUND 1                   Make background color white
      16 FOREGROUND 0                   Make text color black
      20 COLLISION 3,100                Enable lightpen interrupt
      30 DO:LOOP                        Hang here until done
      40 END                            Done
     100 COLLISION 3                    Got one, don't want more
     110 PRINT LPEN(0),LPEN(1)          Display lightpen position
     120 COLLISION 3,100                Re-enable interrupt
     130 RETURN


MID$ -- Substring function

                    MID$ (string, position [,length])

This  function  can  appear  on  the  left  or  the  right  side of an
assignment statement:

Case 1:   string_var = MID$ (string_expression, position [,length])

This  form  returns a piece of another string.  The function returns a
string  of  the  specified  length  taken  from  the string_expression
beginning at the indicated position. The position must be in the range
(1-255),  one  (1)  being  the first character.  The length can be any
number  in  the range (0-255),  or it can be omitted.  If the position
specified   is   greater   than   the  number  of  characters  in  the
string_expression, a null (empty) string is returned. If the length is
greater  than  the number of characters from the given position to the
end of the string_expression,  or the length is omitted,  then all the
rightmost characters beginning at the position are returned.

       A$ = MID$("TICTACTOE",4,3)        Result is A$="TAC"
       A$ = MID$("TICTACTOE",4)          Result is A$="TACTOE"
       A$ = MID$("TICTACTOE",10,1)       Result is AS="" (empty)

Case 2:   MID$ (string_var, position [,length]) = string_expression

This  form  replaces  a  portion of the string contained in string_var
with  data from another string_expression,  beginning at the specified
position  in  the string_var.  If the length is given only,  that many
characters  from the  string_expression  are taken,  otherwise all the
characters  in  the  string_expression  will replace characters in the
string_var beginning at the position specified. The there are too many
characters  to  fit in the string_var,  an 'ILLEGAL QUANTITY' error is
reported. If the length given is zero, no characters will be replaced.

 A$="TICTACTOE": MID$(A$,4,3)="123456"   Result is A$="TIC123TOE"
 A$="TICTACTOE": MID$(A$,4)  ="123456"   Result is A$="TIC123456"
 A$="TICTACTOE": MID$(A$,5)  ="123456"   Result is 'ILLEGAL QUANTITY'


MONITOR -- Enter the built-in machine language monitor

             SEE SECTION 3.2 ON THE C64DX MONITOR.


MOUSE -- Enable or disable the mouse driver

               MOUSE ON [,port [,sprite [,position] ] ]
               MOUSE OFF

    port      = joyport 1, 2, or either (both)         (1-3)
    sprite    = sprite pointer                         (0-7)
    position  = initial pointer location               (x,y)
                normal, relative, or angular coordinate

                defaults to sprite 0, port 2
                ????    add min/max x/y positions

             [*** THIS COMMAND IS SUBJECT TO CHANGE ***]

Mouse  ON  enables  the  built-in  mouse driver.  The user must load a
pointer  into  the proper sprite area ($600-$7FF).  The driver assumes
the  "hot  point"  is the top left corner of the sprite,  and does not
allow this point to leave the screen.

Mouse  OFF  will  turn  off  the  driver  and the currently associated
sprite.

Use the RMOUSE function to get the current pointer position and button
status. See the sample program at RMOUSE.


MOVSPR -- Position sprite or set sprite in motion

                         MOVSPR sprite <,x,y>

Use the  SPRITE command to turn on a sprite and MOVSPR to position it.
Sprites are numbered 0-7. The sprite's position can be specified using
one of the following coordinate types:

        [+/-]x, [+/-]y = [relative] position
                 x#y   = angle and speed
                 x;y   = distance and angle

Angles  are  specified  as  0-360  degrees,  with 0 being straight up.
Speeds  are  specified as a number of pixels per frame, 0-255. Sprites
are  moved  through  each  pixel  so  that  collisions  are accurately
detected.


NEW -- Delete program in memory and clear all variables

                            NEW [RESTORE]

This  command  erases  the  entire  program  in  memory and clears all
variables  and  open  channels  (but  it  does NOT properly close open
disk write files -- used DCLOSE or DCLEAR beforehand). NEW also resets
the runtime stack pointer  (clears GOSUB & FOR/NEXT stacks),  the DATA
pointer, and the PRINTUSING characters.

The  BASIC program in memory is lost unless it was previously SAVEd to
disk.  If  you  have  not  entered  or loaded any BASIC programs since
typing  NEW,  the  RESTORE  option  will  recover the BASIC program in
memory.  But if the BASIC environment has been changed in any way, the
program  may not be restored correctly.  If BASIC can tell something's
wrong, it will report 'PROGRAM MANGLED'.

NEW  can  be  used  in  direct (edit) mode or in a program.  When it's
encountered in a program, the program terminates.


NEXT -- See FOR/NEXT/STEP and RESUME


NOT -- Get the complement of a number

                           NOT (expression)

The  NOT  function  returns  the complement of an integer in the range
(-32768 to 32767). The function operates on the binary value of signed
16-bit  integers.  An  expression  outside of this range will cause an
'ILLEGAL QUAUTITY' error.

                X = NOT(5)               Result is X=-6
                X = NOT(-6)              Result is X=5

NOT  is often used in logical comparisons (such as an IF statement) to
invert  the  result,  since -1 (true) is the result of NOT(0) (false),
and 0 (false) is the result of NOT(-1) (true).

  X = NOT("ABC"="ABC") AND ("DEF"="DEF")      Result is X= 0 (false)
  X = NOT("ABC"="ABC") AND ("DEF"="XYZ")      Result is X=-1 (true)


OFF -- Subcommand used with various BASIC commands.


ON -- Computed GOTO/GOSUB

             ON expression <GOTO|GOSUB> line_number_list

This  is  a  variation  of  the  IF  <expression>  GOTO statement that
branches  to  one  of  several line numbers based upon the value of an
expression.  The  integer value of the evaluated expression determines
which line number in the line_number_list gets control.

If the expression evaluates to one,  the first line number in the list
gets control,  if it's two the second line number gets control, and so
on.  Fractional  parts  of  the value are truncated  (for example, 2.9
becomes  2).  If the value is zero or greater than the number of items
in  the  list the computer takes none of the branches and continues on
with  the  next  statement.  If  the  value  is negative,  an 'ILLEGAL
QUANTITY ERROR' is reported.

The ON/GOSUB statement must call the first line number of a subroutine
and  the subroutine must end with a RETURN statement.  After executing
the  subroutine,  control  is  returned to the statement following the
ON/GOSUB statement.

                  10 INPUT"ENTER A NUMBER 1-3: ",X
                  20 ON X GOTO 100, 200, 300
                  30 PRINT"TOO LOW OR TOO HIGH": RUN
                 100 PRINT"ONE":   RUN
                 200 PRINT"TWO":   RUN
                 300 PRINT"THREE": RUN


OPEN -- Open a channel to a device or disk file

    OPEN logical_chnl_num, device_number [,secondary_adr
                                         [,<filespec|command>]]

Before a program can access a device or a file, an I/O channel must be
opened  to  it to communicate through.  When something is opened,  you
associate a logical channel number with it, and it is with this number
that  all  other  I/O  statements access the device or file.  The OPEN
command can be used in direct (edit) mode or in a program.

The  channel number, device number, and optional secondary address are
integers   from   0-255.   Refer  to  the  device's  manual  for  more
information about what (if any) secondary addresses it uses.


    channel:    0-127    return = output return character only
              128-255    return = output return + linefeed

    device:         0    Keyboard
                    1    Default system drive
                          whatever its number is (see SET DEF)
                    2    RS232
                    3    Screen
                    4-7  Serial bus
                          (usually reserved for printers)

                    8-31 Serial bus
                          (usually reserved for disk drives)

The filespec is the file name in the case of disk files (refer to your
DOS  manual for details).  Typically,  the filename is a string having
the the following form:

                [[@|S]drive:] filename [,type] [,mode]

An  example  would  be  0:MYFILE,SEQ,READ  to open the sequential file
MYFILE  for reading on drive 0.  Disk drives usually support some kind
of  filename pattern matching.  Most disk drives support the following
file types and modes (can be abbreviated to first character):

    types:          'S'equential
                    'P'rogram
                    'R'elative
                    'U'ser

    modes:          'R'ead
                    'W'rite
                    'L'ength (for relative type files)

Some channels or devices accept a command string instead of a filename
when they are opened.  An example would be the disk command channel or
the RS232 open/setup command. Refer to the device's documentation.

    OPEN 1,8,15,"I"        Open CBM disk command channel & send
                              it the 'I'nitialize command.
    OPEN 4,4,7             Open CBM printer channel in upper/lower
                              case mode.
    OPEN 128,2,2,CHR$(14)  Open a 9600 8N1 RS232 channel and
                              translate CR into CRLF on output.

See   also  DOPEN,  DCLOSE,  CLOSE,  CMD,  GET#,  INPUT#,  and  PRINT#
statements and I/O status variables ST, DS, and DS$.


OR -- Boolean operator

                       expression OR expression

The OR operator returns a numeric value equal to the logical OR of two
numeric  expressions,  operating  on the binary value of signed 16-bit
integers  in  the range (-32768 to 32767).  Numbers outside this range
result in an 'ILLEGAL QUANTITY' error.

                X = 4 OR 8              Result is X=12

In  the  case  of  logical  comparisons,  the  numeric value of a true
situation  is  -1  (equivalent  to 65535 or $FFFF hex) and the numeric
value of a false situation is zero.

    X = ("ABC"="ABC") OR ("DEF"="DEF")      Result is X=-l (true)
    X = ("ABC"="ABC") OR ("DEF"="XYZ")      Result is X=-1 (true)
    X = ("ABC"="XYZ") OR ("DEF"="XYZ")      Result is X= 0 (false)


PAINT -- Fill a graphics area with color

                         PAINT x,y, mode [,color]

          x,y     coordinate to begin fill at
          mode    0: fill area to edge = color
                  1: fill area to edge=same as color at x,y

PAINT  fills an enclosed graphic area starting at the given coordinate
with  the  color  of  the  currently  defined PEN.  The mode parameter
identifies the region to be filled.

            [*** THIS COMMAND IS NOT YET IMPLEMENTED ***]


PALETTE -- Define a color

          PALETTE [screen#|COLOR], color#, red, green, blue
          PALETTE RESTORE

          screen# 0-1
          color#  0-255
          red     0-15
          green   0-15
          blue    0-15

The  PALETTE  command  can  be  used  to  define a color for a logical
graphic  screen,  set an absolute color,  or restore the C64DX VIC-III
default colors. PALETTE can be used in direct mode or in a program.

The  VIC-III  pre-defines  the  first  16 colors to the usual C64-type
colors,  but  you  can  change  them with the PALETTE COLOR command or
restore them all with the PALETTE RESTORE command.

See the sample program after the SCREEN command.


PASTE -- Put a CUT graphic area on the screen

                              PASTE x,y

                    [*** NOT YET IMPLEMENTED ***]


PEEK -- Function returning the contents of a memory location

                            PEEK (address)

This  function returns the contents of a memory location.  The address
must  be  an  integer in the range of 0-65535 ($0-$FFFF) and the value
returned will be an integer in the range of 0-255 ($0-$FF).

Use  the  BANK command to specify which 64K memory bank the address is
in.  Note  that  a  BANK  number greater than 127 (i.e., a bank number
with  the  most  significant  bit set)  must be used to address an I/O
location,  such  as the VIC chip or color memory.  Refer to the system
memory map for details. PEEK uses the DMA device to access memory.

Use the POKE command to change the contents of a memory location.

  BANK 0: X = PEEK (208)     Reads the keyboard buffer index. If
                             it's empty, X will be zero, otherwise X
                             will be the number of characters in it.


PEN -- Specify a pen color for drawing on graphic screen

                            PEN pen, color

          pen     0-2
          color   0-255

Before  you  can  draw anything on a graphic screen,  you have to tell
BASIC  what  color  your  PENs are.  You should first define what your
colors are using the PALETTE command,  then use PEN to associate those
colors  with  a  PEN.  Whatever  graphic  commands you use after a PEN
command will use the PEN you specified.

          PEN 0,1         Put color 1 "ink" into draw pen 0

See the sample program after the SCREEN command.


PIC -- Graphic picture subcommand


PLAY -- Play a musical string

                   PLAY "[Vn,On,Tn,Un,Xn,elements]"

             [*** WILL CHANGE TO ADD 2ND SID SUPPORT ***]

The PLAY command lets you select a  voice, octave, instrument, volume,
filter,  and  musical  notes.  All  these parameters are packed into a
string (spaces are allowed for readability).

                On = Octave (n=0-6)
                Tn = Tune envelope # (n=0-9)
                        0= piano        (defaults)
                        1= accordion
                        2= calliope
                        3= drum
                        4= flute
                        5= guitar
                        6= harpsichord
                        7= organ
                        8= trumpet
                        9= xylophone
                Un = Volume (n=0-9)
                Vn = Voice (n=1-3)
                Xn = filter on (n=1), off (n=0)

        Elements:
                A,B,C,D,E,F,G   ... Notes, may be preceded by:
                # ................. Sharp
                S ................. Flat
                . ................. Dotted
                W ................. Whole note
                H ................. Half note
                Q ................. Quarter note
                I ................. Eighth note
                S ................. Sixteenth note
                R ................. Rest
                M ................. Wait for all voices playing to end
                                    (a measure)

Once the music string starts PLAYing,  the computer will continue with
the  next  statement.  The  music will continue to play automatically.
Using  the 'M'easure command will cause the computer to wait until the
music has up to that point has been played out.

Use  the  TEMPO command to alter the tempo (speed) of PLAY.  Note that
the VOLume command can change a PLAY string's volume setting.


POINTER -- Get the address of a variable descriptor

                       POINTER (variable_name)

This  function  returns the address of an entry in the variable table.
If  the  value  returned is zero, the variable is currently undefined.
The  variable  table  is normally in the second RAM bank (BANK 1). See
the section on variable storage for details.

Note that,  while the location of a string descriptor will not change,
the  location  of  the  actual  string in memory changes all the time.
Also,  when  working  with an array name you must specify a particular
element,  to  which  POINTER  will  return a pointer to that element's
descriptor and not to the array descriptor.

     10 A$="FRED"                     Define A$
     20 DESC=POINTER (A$)             Lookup A$ in variable table
     30 BANK1: PRINT PEEK(DESC)       Displays the length of A$


PORE -- Write a byte to memory location

                     POKE address, byte [,byte ...]

POKE  is  used  to  write  one  or  more bytes into one or more memory
locations.  The  address  must  be  an integer in the range of 0-65535
($0-SFFFF) and the value to be written must be an integer in the range
of 0-255 ($0-$FF). If more than one byte is given,  it will be written
into successive memory locations.

Use  the  BANK command to specify which 64K memory bank the address is
in.  Note  that  a  BANK number greater than 127  (i.e., a bank number
with  the  most  significant  bit  set) must be used to address an I/O
location,  such  as the VIC chip or color memory.  Refer to the system
memory map for details. Also note that, unlike previous CBM computers,
POKEs  to a ROM location will not "bleed through" into a corresponding
RAM location. POKE uses the DMA device to access memory.

Use the PEEK function to read a byte from a memory location.

Because  this  command  directly accesses system memory,  extreme care
should  be  taken  in its use.  Altering the wrong memory location can
crash the computer (press the reset button to reboot).

 BANK 0: POKE 208,0                Resets location 208 ($000D0),
                                   clearing the keyboard buffer.

 BANK 128: POKE DEC("D023"),1,2,3  Sets the VIC extended background
                                   colors to 1, 2, and 3 respectively


POLYGON -- Draw a regular n-sided figure on a graphic screen

 POLYGON x,y, xradius,yradius, [solid], angle,drawsides,sides,subtend

         x,y         = center of polygon
         x,yradius   = radii of polygon
         solid       = solid flag            (0-1)
         angle       = starting angle        (0-360)
         drawsides   = # of sides to draw    (3-127)
         sides       = # sides of polygon    (drawsides<=sides)
         subtend     = subtend flag          (0-1)


POS -- Get the column number of the cursor

                               POS(0)

This  function returns the current text column the cursor is in,  with
respect  to  the currently defined window (see RWINDOW).  It's usually
used  to  format  text printed to the screen.  The argument (0) is not
used  for  anything.  POS  will not work as expected if text output is
redirected to a disk file or the printer.

                10 MAXCOL = RWINDOW(l)
                20 FOR ADR=DEC("600") TO DEC("7FF")
                30 PRINT HEX$(PEEK(ADR));" ";
                40 IF POS(0) > (MAXC0L-5) THEN PRINT
                50 NEXT

This  example  illustrates  one  way  to  format output to the screen,
keeping  the  last  item on a line from being split between two lines,
regardless of the window size  (as long as the window size is at least
4 characters wide). It dumps the data for the first sprite in hex.


POT -- Paddle function

                             POT (paddle)

This  function  returns  the  state  of  a game paddle (POTentiometer)
controller in one of the two game ports.

      paddle=1 ..... Position of paddle #1 (port 1, paddle "A")
      paddle=2 ..... Position of paddle #2 (port 1, paddle "B")
      paddle=3 ..... Position of paddle #3 (port 2, paddle "A")
      paddle=4 ..... Position of paddle #4 (port 2, paddle "B")

The value returned by POT ranges from 0 to 255. Any value greater than
255  means  that  the  fire  button  is also pressed. Paddles are read
"backwards"  from normal things like volume knobs or faucets.  A value
of  255 means the paddle has been turned counterclockwise as far as it
will  go  ("off"),  and  a value of 0 means the paddle has been turned
clockwise as far as it will go "on").

Note  that  some paddles are "noisy" and their output must be averaged
or "damped" to prevent whatever they are controlling from jittering.

     10 SPRITE 1,1                      Turn on a sprite
     20 DO                              Begin a loop
     30 X=POT(3)                        Read paddle "A" in port 2
     40 MOVSPR 1,300-(X AND 254),200    Move the sprite
     50 LOOP UNTIL X>255                Loop until button pressed
     60 SPRITE 1,0                      Turn off sprite

This   sample  program  turns  on  a  sprite  and  lets  you  move  it
horizontally  with a paddle. If you press the paddle's fire button, it
turns off the sprite and the program ends. The calculations in line 40
do  several things all at once -- they mask the fire button and "damp"
the  output to reduce jitter by masking the least significant bit (the
X  AND  254  part) and invert the output so that turning the paddle to
the right makes the sprite go right (subtracting result from 300).


PRINT -- Display data on text screen

                   PRINT [expression_list] [<,|;>]

PRINT  will  evaluate  each  item  in the expression_list and pass the
results  to  the  system screen editor to display on the screen.  If a
screen  window is defined,  the output will be confined to the window.
PRINT  can  be  used to send control codes and escape sequences to the
screen  editor  to  do  such  things as set windows, change TAB stops,
change text colors or set reverse field,  or choose cursor styles. See
the section on Editor modes for details.

PRINT can be followed by any of the following:

   Numeric or string expressions      12, "HELLO", 1+1, "S"+STR$(I)
   Variable names                     A, B, A$, X$
   Functions                          ABS(33), HEX$(160)
   Punctuation marks                  ;,
   Nothing

Numeric  values  are always followed by a space.  Positive numbers are
preceded by a space, and negative numbers are preceded by a minus sign
('-').  Scientific notation is used when a number is less than 0.01 or
greater than or equal to 999999999.2 .

A  semicolon (';') or space between list items causes the next item to
be  printed  immediately  following  the previous item.  A comma (',')
causes  the next item to be printed at the next comma stop (similar to
TAB stops,  but every 10 spaces).  These rules apply to the next print
statement,  if  the  expression_list ends with either a semicolon or a
comma,  otherwise  a  return  is  printed.  Note  that  floating point
variable  names  should  not  be separated from the next variable name
with  a space,  and constants should not be preceeded or followed by a
space.

For formatted PRINT output, see the PRINT USING command.

  PRINT "HELLO"                      HELLO

  A$="THERE": PRINT "HELLO ";A$      HELLO THERE

  A=4:B=2: PRINT A+B                 6

  J=41: PRINT J;: PRINT J-1          41  40

  C=A+B:D=B-A: PRINT A;B;C;D         4  2  6 -2
  C=A+B:D=B-A: PRINT A,B,C,D         4         2         6        -2

  A=1:B=2:AB=3: PRINT A B            3
  PRINT 1 2 3, 1 2 3 +1              123       124

  PRINT 0.009, 0.01                  9E-03     .01
  PRINT 999999999; 999999999.2       999999999  1E+09

The  CMD  command  can be used to redirect PRINT output to a device or
file. Also see the POS, SPC, TAB functions, CHAR and PRINT USING.


PRINT# -- Send data to an I/O channel (file)

       PRINT#logical_channel_number [,expression_list] [<,|;>]

This command is used to send (transmit) data to a device or file.  The
logical_channel  number  is  the  number assigned to the device (file)
in an OPEN (or DOPEN) statement.  The output is otherwise identical to
that   of  a  PRINT  statement,  including  the  comma  and  semicolon
conventions.  Note that certain screen-oriented functions, such as TAB
and SPC do not have the same effect as they do with screen I/O.

It's  good  practice  to  examine the I/O status byte (and the DS disk
status for file I/O) after every I/O instruction to check for problems
or errors.

For formatted output, use the PRINT# USING command.

    10 OPEN 1,8,15                  Initialize disk drive
    20 PRINT#1,"I"                  (same as DCLEAR)
    30 CLOSE 1

    10 DOPEN#1,"NEWFILE",W          Create a SEQ file
    20 FOR I=1 TO 10
    30 PRINT#1, I, STR$(I)          Write numbers 1-10 to it
    40 NEXT
    50 DCLOSE#1

    10 OPEN 2,2,2,CHR$(12)          Open 1200 baud RS232 channel
    20 PRINT#2, "ATDT,5551212"      Send modem a Hayes dial command


PRINT USING -- Output formatted data to the screen, device, or file

PRINT [#logical_channel_number,] USING format; expression_list [<,|:>]

Read  about  the  PRINT  and  PRINT#  commands  first  for information
regarding  the  syntax of the expression list and,  for device output,
establishing the logical_channel_number.

The items in the expression list must be separated by commas (',').

The  format  is  defined in a string literal or string variable and is
described   below.   See  the  PUDEF  command  for  specifing  special
formatting characters. The various formatting characters are:

         CHARACTER            SYMBOL         NUMERIC   STRING
         ----------------     ------         -------   ------
         Pound sign             #               X        X
         Plus sign              +               X
         Minus sign             -               X
         Decimal Point          .               X
         Comma                  ,               X
         Dollar Sign            $               X
         Four Carets            ^^^^            X
         Equal Sign             =                        X
         Greater Than Sign      >                        X

The  pound  sign  ('#')  reserves  room  for a single character in the
output  field.  If  the  data  item  contains more characters than the
number  of  pound signs in the format field,  the entire field will be
filled with asterisks ('*').

                       10 PRINT USING "####";X

For these values of X, this format displays:

                       A = 12.34      12
                       A = 567.89     568
                       A = 123456     ****

For  a  STRING item, the string data is truncated at the bounds of the
field.  Only  as  many characters are printed as there are pound signs
in the format item. Truncation occurs on the right.

The  plus  ('+') and minus ('-') signs can be used in either the first
or  last  position  of  a format field but not both.  The plus sign is
printed  if  the number is positive.  The minus sign is printed if the
number is negative.

If a minus sign is used and the number is positive, a blank is printed
in the character position indicated by the minus sign.

If  neither  a  plus sign nor a minus sign is used in the format field
for  a  numeric  data  item,  a minus sign is printed before the first
digit  or  dollar  symbol  if  the  number  is negative and no sign is
printed if the number is positive.  This means that one more character
is printed if the number is positive.  If there are too many digits to
fit into the field specified by the pound sign and +/- signs,  then an
overflow occurs and the field is filled with asterisks ('*').

A  decimal  point  ('.') symbol designates the position of the decimal
point in the number. There can be only one decimal point in any format
field.  If  a decimal point is not specified in the format field,  the
number  is  rounded  to  the  nearest  integer and printed without any
decimal places.

When a decimal point is specified,  the number of digits preceding the
decimal  point  (including the minus sign,  if the number is negative)
must not exceed the number of pound signs before the decimal point. If
there  are  too many digits an overflow occurs and the field is filled
with asterisks ('*').

A comma (',') allows placing of commas in numeric fields. The position
of  the comma in the format list indicates where the commas appears in
a  printed  number.  Only  commas within a number are printed.  Unused
commas  to the left of the first digit appear as the filler character.
At least one pound sign must precede the first comma in a field.

If commas are specified in a field and the number is negative,  then a
minus  sign  is  printed  as the first character even if the character
position is specified as a comma.

    FIELD    EXPRESSION    RESULT   COMMENT
    ------   -----------   ------   -----------------------------
     ##.#       -.1         -0.1    Leading zero added
     ##.#         1         1.0     Trailing zero added
     ####      -100.5       -101    Rounded to no decimal places
     ###.        10         10.     Decimal point added
     #$##         1         $1      Leading dollar sign
     ####      -1000        ****    Overflow because 4 digits and
                                    minus sign don't fit in field

A dollar sign ('$') symbol shows that a dollar sign will be printed in
the  number.  If the dollar sign is to float  (always be placed before
the  number),  specify at least one pound sign before the dollar sign.
If a dollar sign is specified without a leading pound sign, the dollar
sign  is printed in the position shown in the format field.  If commas
and/or  a  plus  or  minus  sign is specified in a format field with a
dollar  sign,  the  program  prints  a comma or sign before the dollar
sign.  The four up arrows or carets symbol is used to specify that the
the number is to be printed in E format (scientific notation). A pound
sign  must  be  used  in addition to the four up arrows to specify the
field  width.  The  arrows can appear either before or after the pound
sign in the format field.  Four carats must be specified when a number
is  to  be  printed in E format.  If more than one but fewer than four
carats are specified, a syntax error results. If more than four carats
are  specified  only  the  first  four  are  used.  The fifth carat is
interpreted  as  a  no  text  symbol.  An  equal sign ('=') is used to
center a string in a field. The field width is specified by the number
of characters  (pound sign and =)  in the format field.  If the string
contains fewer characters than the field width, the string is centered
in  the field.  If the string contains more characters that can be fit
into  the  field,  then the rightmost characters are truncated and the
string  fills  the entire field.  A greater than sign ('>') is used to
right justify a string in a field.

                   5 X=32: Y=100.23: A$="TEST"
                  10 PRINT USING "$##.## ";13.25,X,Y
                  20 PRINT USING "###>#";"CBM",A$

When this is RUN, the following output appears on the screen:

                  $13.25 $32.00 $*****
                    CBM TEST

$*****  is printed instead of Y because Y has 5 digits,  which exceeds
the  format specification.  The second line asks for the strings to be
right justified, which they are.


PUDEF -- Redefine PRINT USING symbols

                       PUDEF definition_string

PUDEF  allows  redefinition  of  up  to  4  symbols in the PRINT USING
statement.  Blanks,  commas,  decimal  points, and dollar signs can be
changed  into some other character by placing the new character in the
correct position in the PUDEF definition_string.

Position 1 is the filler character.  The default is a space character.
Place another character here to be used instead of spaces. Similarly,

Position 2 is the comma character. Default is a comma.
Position 3 is the decimal point.
Position 4 is the dollar sign.

        10 PUDEF "*"         PRINTs * in the place of blanks.
        20 PUDEF " @"        PRINTs @ in place of commas.


QUIT -- [*** UNIMPLEMENTED ***]

RCLR -- Get the current screen color

                             RCLR(source)

                  [*** CURRENTLY UNIMPLEMENTED ***]

This function returns the color assigned to source as an number in the
range of 0-15. The color sources are:

                       0 = background
                       1 = foreground
                       2 = multicolor 1
                       3 = multicolor 2
                       4 = border
                       5 = highlight color


RDOT -- Get the current position or color of the pixel cursor

                             RDOT(source)

                  [*** CURRENTLY UNIMPLEMENTED ***]

This function returns information about the current pixel location.

                        0 = current X position
                        1 = current Y position


READ -- Read data from DATA statements

                          READ variable_list

READ  statements are used along with DATA statements.  READ statements
read  data  from  DATA  statements into variables,  just like an INPUT
statement reads data typed by the user. READ statements can be used in
direct or program mode, but DATA statements must be in a program.

The  variable  types  in the variable_list must match the type of DATA
being  read,  or  a  'TYPE MISMATCH'  error is reported.  If there are
insufficient data in the program's  DATA  statements  to  satisfy  all
of  the  variables  in  the READ statement,  an 'OUT OF DATA' error is
reported.

The computer maintains a pointer to the next DATA item to be read by a
READ  statement.  Initially  this  pointer  points to the beginning of
the  program.  As  each  variable  in a READ statement is filled,  the
computer  moves  the  DATA pointer to the next DATA item.  If all of a
READ  statement's variables are filled before all of the data has been
read from a DATA statement, the next READ statement will begin reading
data at the point where the previous READ stopped.

The  DATA  pointer  can  be changed by the RESTORE command.  It can be
reset  back to the beginning of the program,  or pointed to a specific
line number. See RESTORE.

    10 DATA 100, 200, FRED, "HELLO, MOM", , 3.14, ABC123, -1.7E-9
    20 READ X,Y
    30 READ NAME$, MSG$, NULL$
    40 READ PI, JUNK$, S
    50 RESTORE


RECORD -- Specify a relative disk file record number

            RECORD #logical_channel_number, record [,byte]

This command allows you to access any part of any record in a RELative
type disk file.  If the byte parameter is omitted,  the access pointer
is pointed at the first byte of the specified record number.

Before  you can use RECORD,  you must OPEN a file.  See OPEN and DOPEN
for instructions.  Also refer to your DOS manual for an explanation of
RELative type files.

 10 INPUT"ENTER RELATIVE FILENAME: ",F$  get name of existing file
 20 DOPEN#1, (F$),L: PRINT DS$           open it & display disk status
 30 R=1: INPUT"ENTER RECORD NUMBER: ",R  get a record number
 40 B=1: INPUT"ENTER BYTE (RETURN): ",B  get byte number, if any
 50 RECORD#1, R,B                        position file pointer
 60 INPUT#1, REC$                        read the record
 70 PRINT REC$                           display the record
 80 PRINT "CONTINUE? (Y/N)"
 90 GETKEY A$: IF A$="Y" THEN 30
100 DCLOSE#1                             close the file


REM -- Place an explanatory remark or comment in a program

                        REM plain text message

The  REMark  command  is  just  a  way  to leave a note to whomever is
reading  a  LISTing of the program.  It might explain a section of the
program, give information about the author, etc.

REM  statements  in no way effect the operation of the program, except
to  add  length to it (and therefore slow it down a little).  No other
executable statement can follow a REMark on the same line.

     10 REM  THIS PROGRAM WAS WRITTEN ON 2/14/91 BY F.BOWEN
     20 REM  SAMPLE PROGRAM
     30 :
     40 DIR                     :REM  DISPLAY THE DISK DIRECTORY
     50 LIST "SAMPLE PROGRAM"   :REM  DISPLAY THIS PROGRAM
     60 END


RENAME -- Rename a disk file

       RENAME "oldname" TO "newname" [,Ddrive] [<ON|,>Udevice]

The  RENAME  command changes the name of a file in the disk directory.
Pattern  matching  is  not  allowed,  and  "newname"  must  be a valid
filename  that  does  not  already  exist on the disk.  The file being
renamed does not need to be open.

       RENAME "TEST" TO "FINALTEST"
       RENAME (OLD$) TO (OLD$+".OLD") ON U(DEV)


RENUMBER -- Renumber the lines of a BASIC program

   RENUMBER [new_starting_line [,[increment] [,old_starting_line]]]

Renumber  is used to resequence the line numbers of a BASIC program in
memory.  All  or  part  of  a program can be renumbered.  The RENUMBER
command  first  scans  the  program  to make sure all the line numbers
referenced in commands  (such as GOTO, GOSUB, TRAP, etc.) exist,  that
new line numbers are in the legal range, and that changing the program
would  not  overflow the available memory.  An 'UNRESOLVED REFERENCE',
'LINE  NUMBER  TOO  LARGE',  or  'OUT  OF MEMORY' error is reported if
there's  a  problem,  and  RENUMBER  is automatically canceled without
having changed anything.

If  the program passes all the checks,  RENUMBER changes the specified
line  numbers and updates all references to the old numbers throughout
the program and relinks the program.

The  new_starting_line  is the number of the first line in the program
after  renumbering.  It  defaults to 10.  The increment is the spacing
between line numbers  (eg., 10, 20, 30 would mean an increment of 10).
It  also  defaults to 10.  The old_starting_line is the line number in
the program where you want renumbering to begin.

RENUMBER can be used in direct (edit) mode only. Note that line number
zero (0) is a valid line number.

    RENUMBER                Renumbers the entire program. After
                            renumbering, the first line will be 10
                            the second 20, etc. through the end
                            of the program.

    RENUMBER ,1             Renumbers the entire program as above,
                            but in increments of one. The first
                            line will be 10, the second 11, etc.

    RENUMBER 100, 5, 80     Starting at line 80, renumbers the
                            program. Line 80 becomes line 100,
                            and lines after that are numbered in
                            increments of 5, through the end of
                            the program.

    RENUMBER ,,65           Starting at line 65, renumbers lines
                            in increments of 10, starting at line
                            10 through the rest of the program.


RESTORE -- Position READ pointer at specific DATA statement

                            RESTORE [line]

The computer maintains a pointer to the next DATA item to be read by a
READ  statement.  Initially  this  pointer  points to the beginning of
the program. The DATA pointer can be changed by the RESTORE command.

Using  RESTORE  without  specifying  a line number will reset the DATA
pointer  back  to  the  beginning of the program.  If a line number is
specified, the DATA pointer is pointed to that line. The line does not
have  to  contain  a  DATA  statement.  When the computer executes the
next  READ statement,  it will look for the next DATA item starting at
the line the DATA pointer is at.

See the READ command an example.


RESUME - Resume program execution after error TRAP

                          RESUME [line|NEXT]

Used to return to execution after TRAPping an error.  If a line number
is given, the computer performs a 'GOTO line' and resumes execution at
that  line.  RESUME NEXT  resumes execution at the statement following
the  one  that  cause  the  error.  RESUME without any parameters will
resume execution at the statement that cause the error.

If  the  computer  encounters  a  RESUME  statement  outside of a TRAP
routine  or  if  a  TRAP  was  not in effect a 'CAN'T RESUME' error is
reported. RESUME can only be used in program mode.

                    10 TRAP 90
                    20 FOR I=-5 TO 5
                    30 PRINT 5/I
                    40 NEXT
                    50 END
                    60 :
                    90 PRINT ERR$(ER): RESUME NEXT


RETURN -- Return from subroutine or event handler

                                RETURN

This statement is associated with the GOSUB (GO SUBroutine) statement.
When  a  subroutine  is  called  by  a GOSUB  statement,  the computer
remembers  where  it's  at  before  it calls the subroutine.  When the
computer  encounters  a  RETURN statement,  it returns to the place it
last encountered a GOSUB and continues with the next statement.

If there wasn't a previous GOSUB,  then a 'RETURN WITHOUT GOSUB' error
is reported.

RETURN  is  also  used  by  event  handlers,  set  up by the COLLISION
command. See COLLISION.


RGR -- Get the current graphic mode

                                RGR(0)

                  [*** CURRENTLY UNIMPLEMENTED ***]

This function returns current graphic mode. A result of zero means the
display is text, a non-zero result means it's graphic.


RIGHT$ -- Get the rightmost characters of a string

                        RIGHT$ (string,count)

This function returns a string containing the rightmost 'count' number
of characters of the string expression. Count is an numeric expression
in  the  range (0-255).  If  count  is  greater than the length of the
string,  the entire string will be returned.  If count is zero, a null
(empty) string will be returned.

          A$ = RIGHT$("123ABC",3)         Result is A$="ABC"


RMOUSE -- Get the mouse position and button status

              RMOUSE [Xposition [,Yposition [,button]]]

              X,Yposition = current position of mouse pointer sprite
              Button      = current status of mouse buttons
                              0   = no button
                              1   = right button
                              128 = left button
                              129 = both buttons
RMOUSE is a command which retrieves a mouse's current position and the
state  of its buttons,  and places this information into the specified
numeric  variables.  If a mouse is not installed, "-1" is returned for
all variables.  If both ports are enabled,  buttons from each port are
merged. Use the MOUSE command to turn a mouse on or off.

   10 MOUSE ON, 2, 1           Turn mouse on, port 2, sprite 1
   20 DO                       Begin loop
   30 RMOUSE X, Y, B           Get mouse position & buttons
   40 PRINTUSING"### ";X,Y,B   Show  "       "         "
   50 LOOP UNTIL B=129         Loop until user presses both buttons
   60 MOUSE OFF                Turn mouse off


RND -- Get a pseudo-random number

                              RND (type)

The  RND function returns a pseudo RaNDom number between 0 and 1.  The
random sequence returned is determined by the type parameter:

  type = 0    Returns a random number based upon the system clock.
  type < 0    Negative numbers "seed" the random number generator,
              defining a new but reproducible random sequence.
  type > 0    Positive numbers draw the next random number from the
              sequence defined by the last "seed" value.

This  lets  a  programmer  use a reproducible sequence while debugging
(fixing)  a  program,  so that random errors can be easily reproduced.
Once the program has been fixed, it can be "seeded" such that a random
sequence is used every time the program is run.

               10 DO
               20 INPUT "SEED"; S
               30 IF S=0 THEN END
               40 FOR I=1 TO S
               50 PRINT INT(RND(1)*6)+1, INT(RND(1)*6)+1
               60 NEXT
               70 LOOP

The  above  program will demonstrate the results of seeding the random
number  generator.  It  lets  you  specify a positive or negative seed
value,  and  then  prints  the  first S random pairs of that sequence.
Enter a zero to end the program.  The calculations in line 50 make the
random numbers be integers from 1 to 6, like dice.  Type in a negative
dice from that sequence.  Every time you enter "-1",  for example, you
will roll the same numbers:

                     first roll        2 and 6
                     second            6 and 1
                     third             1 and 1
                     fourth            1 and 4
                     fifth             5 and 5

Games  and  statistical programs should use RND(0) for true randomness
or seed the generator with a random number, such as RND(-TI).

The general form for getting random integers using RND is:

                       INT( RND(0) * MAX ) + 1

where MAX is the highest number you can get. This gives you numbers as
low  as  1 and as high as MAX.  For dice,  MAX is 6 (or 12 if you want
to simulate rolling two dice at once). For cards, MAX is 52.

                        INT( RND(0) * 16)

This  form  will return integers from zero to 15,  which is useful for
generating random colour values, for example.


RREG -- Get register data after a SYS call

       RREG [a_reg] [,[x_reg] [,[y_reg] [,[z_reg] [,status] ]]]

Following  a SYS call,  the RREG command retrieves the contents of the
microprocessor's  registers  and  puts them into the specified numeric
variables. See the sample program at SYS.


RSPCOLOR -- Get multicolor sprite colors

                        RSPCOLOR (multicolor#)

Returns the current colors for multicolor sprites.  Color values range
from 0-15. Use RSPRITE function to get the foreground sprite color.

                  multicolor# = 1 gets multicolor #1
                  multicolor# = 2 gets multicolor #2

See SPRITE and SPRCOLOR.


RSPPOS -- Get the location and speed of a sprite

                      RSPPOS (sprite,parameter)

The  RSPPOS  function  returns the current X or Y position of a sprite
and  its speed,  set by the MOVSPR command.  A sprite does not have to
be  on  to use RSPPOS.  The sprite number must be in the range of 0-7,
and the parameter is:

                    0 to get current X position
                    1 to get current Y position
                    2 to get current speed (0-255)


RSPRITE -- Get information about a sprite

                      RSPRITE (sprite,parameter)

The RSPRITE function returns the current state of a sprite, set by the
SPRITE command. The sprite number must be in the range of 0-7, and the
parameter is:

        0   to see if it's turned on           (1)=yes  (0)=no
        1   to get sprite foreground color     (0-15)
        2   to get priority over background    (1)=yes  (0)=no
        3   to get X-expansion factor          (1)=yes  (0)=no
        4   to get Y-expansion factor          (1)=yes  (0)=no
        5   to get multicolor factor           (1)=yes  (0)=no


RUN -- execute BASIC program

               RUN [line #]
               RUN "filename" [,Ddrive] [<On|,>Udevice]

RUN  executes  the  BASIC  program  that  is currently in memory.  The
program has to be  LOADed  (DLOAD)  or manually typed in before it can
be executed.  If a line number is specified,  execution begins at that
line.  If a filename is specified, the program is automatically loaded
from disk into memory and executed. RUN can be used in a program.

RUN  clears  all variables and open channels (but it does NOT properly
close open disk write files -- used DCLOSE or DCLEAR beforehand).  RUN
also resets the runtime stack pointer (clears GOSUB & FOR/NEXT stacks)
the DATA pointer,  and the PRINT USING characters.  To start a program
without initializing everything, use GOTO.

   RUN              Starts the program at the first line.
   RUN 100          Starts the program at line 100.
   RUN "TEST"       Loads the program TEST from the, default system
                    disk and starts the program at the first line.


RWINDOW -- Get information about the current text window

                         RWINDOW (parameter)

This  is a function that returns information about the current console
text display. The parameter is specified as:

        0      to get the maximum line # in the current window
        1      to get the maximum column # in the current window
        2      to get the screen size, either 40 or 80 columns


SAVE -- Save a BASIC program in memory to disk

             SAVE "[[@]drive:]filename" [,device_number]

This  command  copies  a  BASIC program in the computer's BASIC memory
area  into  a PRoGram-type disk file.  If the file already exists, the
program is NOT stored and the error message 'FILE EXISTS' is reported.
If the filename is preceded with an '@0:',  then if the file exists it
will  be  replaced by the program in memory.  Because of some problems
with  the 'save-with-replace' option on older disk drives,  using this
option  is not recommended if you do not know what disk drive is being
used  (DELETE  the  file  before  SAVEing).  Pattern  matching  is not
allowed.  In the case of dual drive systems,  the drive number must be
part of the filename.

Use  the  VERIFY  or  DVERIFY command to compare the program in memory
with  a  program  on  disk.  To  save a binary program,  use the BSAVE
command.

    SAVE "myprogram"       Creates the PRG-type file MYPROGRAM
                           on the default system disk and copies
                           the BASIC program in memory into it.

    SAVE "@0:myprogram"    Replaces the PRG-type file MYPROGRAM
                           with a new version of MYPROGRAM. If
                           MYPROGRAM doesn't exist, it's created.

    SAVE F$,9              Saves a program whose name is in F$
                           on disk unit 9.


SCALE -- Set the logical dimension of the graphic screen

                    [*** NOT YET IMPLEMENTED ***]


SCNCLR -- Clear a text or graphic screen

                            SCNCLR [color]

This  command  will  clear the current text window if [color] omitted,
otherwise it will clear the current graphic  screen  using  the  given
color value. See also SCREEN CLR.

    SCNCLR         Clears the text screen. If a window is defined
                   it clears only the window area.

    SCNCLR 0       Clears the current graphic screen with color 0.


SCRATCH -- Delete files from disk directory
           Recover accidentally deleted files

          SCRATCH "filespec" [,Ddrive] [<ON|,>Udevice] [,R]

SCRATCH,  ERASE,  or  DELETE  are different names of the same command.
They are used to delete a file from a disk directory, or optionally to
recover  if  possible an accidentally deleted file.  The diskette must
not be 'write protected', or a 'WRITE PROTECT ON' error is reported.

WARNING:  Deleting a file will destroy all existing data in that file.
Be  extremely  careful  if  you are using pattern matching,  which can
delete any or all files. In direct mode, you are asked to confirm what
you  are  doing  with 'ARE YOU SURE?'.  Type 'Y' and press <RETURN> to
proceed,  or type any OTHER CHARACTER and press <RETURN> to cancel the
command. In program mode there is no confirmation prompt.

Upon  completion,  in  direct mode only, the computer will display the
number of files deleted.

Refer  to  your  disk manual for other details.  Different disk drives
implement   slightly  different  pattern  matching  rules  or  support
features such a specially protected files.

If the 'R'ecover option is present and the DOS supports it,  a deleted
file can be recovered if nothing else has been written to the diskette
since  the  file was accidentally deleted.  You will still be asked to
confirm  the operation,  and upon completion the computer will display
the number of files restored.

    SCRATCH "oldfile"       Deletes the file OLDFILE from the disk
                            in the default system drive.

    SCRATCH "file.*"        Deletes all files beginning with FILE.

    SCRATCH (F$), U(DD)     Deletes the file whose name is in F$
                            from the disk in device DD.

    SCRATCH "SAVEME", R     Attempt to recover the program SAVEME.


SCREEN -- Graphic command

The  SCREEN  command is used to initiate a graphic command.  It always
precedes  another  command word which identifies the graphic operation
to be performed:

SCREEN CLR      - Set graphic screen color

                          SCREEN CLR color#

Clears  (erases)  the  currently opened graphic screen using the given
color value. Use SCNCLR to clear a text screen. See also SCNCLR.

SCREEN DEF      - Define a graphic screen

               SCREEN DEF screen#, width, height, depth

                 screen#      0-1
                 width        0=320, 1=640, 2=1280
                 height       0=200, 1=400
                 depth        1-8 bitplanes (2-256 colors)

Defines a logical screen (numbered 0 or 1), specifies its size and how
many  colors  (bitplanes)  it  has.  It  does  not allow access to the
screen and it does not display the screen.  The screen must be defined
before it is opened for viewing and/or drawing to.

SCREEN SET      - Set draw and view screens

                 SCREEN SET  DrawScreen#, ViewScreen#

                        draw screen #   0-1
                        view screen #   0-1

This  command specifies which logical screen is to be viewed and which
logical  screen  is  to be accessed by the various draw commands.  The
screen  must  be defined and opened first.  Both the draw and the view
screen can be,  and usually are,  the same logical screen.  For double
buffering, they are different.

SCREEN OPEN     - Open a screen for access

                SCREEN OPEN  screen# [,error_variable]

                screen#         0-1
                error_variable  [*** NOT YET IMPLEMENTED ***]

This  command  actually sets up the screen and allocates the necessary
memory for it.  If it's the view screen it will be displayed.  If it's
the draw screen, it can now be drawn to. If there is not enough memory
for the screen,  'NO GRAPHICS AREA'  is reported and the screen is not
opened.

SCREEN CLOSE    - Close a screen

                        SCREEN CLOSE  screen#

                          screen#       0-1

This command closes a logical screen,  ending access to it by the draw
commands if it's the draw screen and restoring the text screen if it's
the view screen.  SCREEN CLOSE deallocates any memory reserved for the
screen.

                       SAMPLE GRAPHIC PROGRAM:

  1 TRAP 170                        in case of error want text screen
 10 GRAPHIC CLR                     initialize graphics
 20 SCREEN DEF 1,0,0,2              define a 320x200x2 graphic screen
 30 SCREEN OPEN 1                   open it
 40 PALETTE 1,0,  0, 0, 0           define screen 1 color 0 = black
 50 PALETTE 1,1, 15, 0, 0           define screen 1 color 1 = red
 55 PALETTE 1,2,  0, 0,15           define screen 1 color 2 = blue
 60 PALETTE 1,3,  0,15, 0           define screen 1 color 3 = green
 70 SCREEN SET 1,1                  make it the view screen
 80 SCNCLR 0                        clear screen with palette color 0
 90 BORDER 0                        set border color to color 0
100 PEN 0,1                         make draw pen = color 1 (red)
110 LINE 100,100, 150,150           draw a diagonal red line
120 PEN 0,2                         make draw pen = color 2 (blue)
130 BOX 50,50, 50,80, 80,50, 80,80  draw a blue box
140 PEN 0,3                         make draw pen = color 3 (green)
150 CHAR 25,50, 1,1,2, "WORDS"      draw green text
160 SLEEP 5                         pause for 5 seconds
170 SCREEN CLOSE 1                  close graphic, get text screen
180 PALETTE RESTORE                 restore normal system colors
190 BORDER 6                        restore normal border color
200 END


SET -- Set various system parameters

The SET command is used to set a system parameter.  It always precedes
another command word which identifies the parameter to be changed:

SET DEF         - Set default system disk drive

                            SET DEF device

The BASIC  DOS commands default to disk unit 8.  Use SET DEF to change
which device these commands default to. This command does not renumber
a disk device, use SET DISK for that.  Commands which specify a device
will  still  access  the device they specified.  A program can be made
more "user friendly" by either not specifying a drive  (thus using the
user's  preferred  drive)  or by specifying device 1.  Device number 1
means "use the system default drive, whatever its number is."

      10 DIR                 gets directory of device 8
      20 DIR U1              gets directory of device 8
      30 DIR U10             gets directory of device 10
      40 SET DEF 10          change the default drive to unit 10
      50 DIR                 gets directory of device 10
      60 DIR U1              gets directory of device 10
      70 DIR U8              gets directory of device 8

SET DISK        - Change a disk device number

                   SET DISK oldnumber TO newnumber

Use this command to renumber (change) a disk drive's unit number.  Not
all  drives  can  be renumbered -- refer to your disk drive manual for
details.  This  command  sends  to  the  disk's  command  channel  the
conventional  CBM  serial disk drive "M-W" command.  See also the DISK
command, which lets you send any command to a disk drive.

         SET DISK 8 TO 10        Change unit 8's number to 10

Because  the  built-in C64DX drives always take precedence over serial
bus drives, this is one way to get the built-in drive "out of the way"
so that you can access a serial bus drive #8.


SGN -- Get the sign of a number

                           SGN (expression)

The SiGN function returns the sign of a numeric expression as follows:

         If the expression is < 0 (negative) .... returns -1
         If the expression is = 0 (zero) ........ returns  0
         If the expression is > 0 (positive) .... returns  1


SIN -- Sine function

                           SIN (expression)

This  function returns the sine of X,  where X is an angle measured in
radians. The result is in the range -1 to 1.

           X = SIN (pi/4)          Result is X=0.707106781

To get the sine of an angle measured in degrees,  multiply the numeric
expression by pi/180.


SLEEP -- Pause program execution of a specified period of time

                            SLEEP seconds

Temporarily suspends execution of your program for 1 to 65535 seconds.


SLOW -- Set system speed to 1.02MHz

SLOW  is  used  primarily  to directly access "slow mode only" devices
such as the SID sound chips. FAST is the default system speed.


SOUND -- Produce sound effects

          SOUND v, f, d [,[dir] [,[m] [,[s] [,[w] [,p] ]]]]

 v   = voice          (1-6)
 f   = frequency      (0-65535)
 d   = duration       (0-32767)
 dir = step direction (0(up), 1(down), or 2(oscillate))   default=0
 m   = min frequency  (0-65535)                           default=0
 s   = sweep          (0-65535)                           default=0
 w   = waveform       (0=triangle,1=saw,2=square,3=noise) default=2
 p   = pulse width    (0-4095)             50% duty cycle=default=2048

The  sound  command is a fast and easy way to create sound effects and
musical  tones.  The first three parameters are required to select the
voice, frequency, and duration of the tone.  The duration is specified
in "jiffies" (60 jiffies = 1 second).

Optionally,  you  can  specify a waveform and,  for square waves,  the
pulse  width.  The SOUND command can sweep a voice through a series of
equally-spaced  frequencies.  The direction of the sweep,  minimum and
maximum  frequencies  can  be  programmed.  If time expires before the
sweep is done, the sound stops. If the minimum or maximum frequency is
reached before time expires, the sound repeats.

For programming details, refer to the SID hardware documentation.  Use
the  VOLume  command to change the volume of the sound.  Note that the
TEMPO command affects PLAY strings only, not SOUND effects.

                     FREQout = ( f * 0.0596 ) Hz
                     PWout = ( p / 40.95 ) %

Each  voice can be programmed separately and played simultaneously for
a  wide  variety  of sound effects.  Once a sound effect is initiated,
BASIC  execution  continues  with  the  next statement while the sound
plays  out,  allowing you to combine and control graphics,  animation,
and sound from a BASIC program. The examples below include information
about  how  to  generate  precise tones for exact times,  but for most
casual users trial and error are perfectly acceptable!  (Note that the
values used are for 60Hz (NTSC) systems):

Using voice 1, emit a square-wave, 440Hz tone for 1 second.  Note that
440Hz = 7382 * 0.0596 using the above formula.

                          SOUND 1, 7382, 60

Using  voice  2,  sweep  from  100Hz  (m=1638)  to  440Hz  (f=7382) in
increments  of  1Hz  (s=17).  The  time  required  to  do  this can be
calculated as t=(f-m)/s, so t=336 jiffies.

                   SOUND 2, 7382, 336, 0, 1678, 17

Using  voice  3,  make a neat sound using an oscillating sweep (dir=2)
and a sawtooth waveform (w=1) for 3 seconds (t=180).

                 SOUND 3, 5000, 180, 2, 3000, 500, 1


SPC -- Space PRINT output

                             SPC (number)

The  SPaCe  function  is  used to format PRINTed data to the screen, a
printer,  or a file.  It specifies the number of spaces to be skipped,
from 0 to 255. A semicolon (';') is always assumed to follow SPC, even
if it appears at the end of a print line.

The  SPC  function  works a little differently on screen,  printer and
disk output.  On the screen,  SPC skips over characters already on the
screen,  which  is  not  the  case  with  printer and disk output.  On
printers,  if  the  last  character on a line is skipped,  the printer
will automatically perform a carriage return and linefeed.

         PRINT "123";SPC(3);"456"       Displays '123   456'

         PRINT "X";SPC(5) :PRINT"X"     Displays 'X     X'

See also the TAB function. A better way to format PRINT output is with
PRINT USING.


SPRCOLOR -- Set multicolor sprite colors

                SPRCOLOR [sprite_mc1] [,sprite_mc2]

Use the SPRITE command to set up a multicolor sprite, and use SPRCOLOR
to set the additional colors. Note that these colors are common to all
multicolor sprites.  The color values must be in the range (0-15). Use
the RSPCOL0R function to get the current multicolor sprite colors, and
RSPRITE to get the current sprite foreground color.


SPRDEF -- Define a sprite pattern

               [*** NOT EXPECTED TO BE IMPLEMENTED ***]


SPRITE -- Turn a sprite on or off, and set its characteristics

SPRITE number [,[on] [,[color] [,[priority] [,[x_exp] [,[y_exp] [,mode] ]]]]]

The  SPRITE  command  allows  you  set all of the characteristics of a
sprite.  Use  the  MOVSPR  command to position it or set it in motion.
Use the SPRCOLOR to set the multicolor sprite colors, if you are using
multicolor sprites.

All the parameters except the sprite number are optional. If you don't
specify a parameter then it won't be changed.

        number  = sprite number                 (0-7)
        on      = enable (1) or disable(0)
        color   = sprite foreground color       (0-15)
        priority= sprite to display data priority:
                        0 means sprite goes over screen data
                        1 means sprite goes under screen data
        x,y_exp = sprite expansion on (1) or off (0)
        mode    = sprite mode:
                        0 high resolution
                        1 multicolor

The  SPRITE  command does not define a sprite.  The sprite definitions
must  be loaded into the sprite area first ($600-$7FF).  Use the BLOAD
and  BSAVE commands.  [*** THIS MAY CHANGE ***]  A sprite is 24 pixels
wide and 21 pixels high.  Each sprite definition requires 63 ($40 hex)
bytes:

                      $600    Sprite 0 definition
                      $640   Sprite 1 definition
                      $680    Sprite 2 definition
                      $6C0    Sprite 3 definition
                      $700    Sprite 4 definition
                      $740    Sprite 5 definition
                      $780    Sprite 6 definition
                      $7C0    Sprite 7 definition

Use  the  RSPRITE function to read a sprite's characteristics,  or the
RSPPOS  function  to  read a sprite's position.  The RSPCOLOR function
is used to get the current multicolor sprite colors.

 10 BLOAD"sprite 1 data",           Load sprite 1's definition
    P(DEC("640"))
 20 SPRITE 1, 1, 2                  Turn it on, make it red
 30 MOVSPR 1, 24, 50                Put it at top-leftmost corner
 40 SPRSAV 1, 2                     Copy sprite 1 definition to 2
 50 SPRITE 2, 1, 7                  Turn on sprite 2 make it yellow
 60 MOVSPR 2, 320, 229              Put it at bottom-rightmost corner
 70 BSAVE"sprite 2 data",           Save sprite 2
    P(DEC("680")) TO P(DEC("6C0"))
 80 SPRITE 1, 0                     Turn off sprite 1
 90 SPRITE 2, 0                     Turn off sprite 2


SPRSAV -- Copy a sprite definition

                      SPRSAV source, destination

Use  this command to copy a sprite's data (shape) to another sprite or
into a string variable,  or copy a shape from a string variable into a
sprite.  You  can  have  many different sprite shapes in memory at one
time,  all  stored  in  strings.  This  makes  it  possible to animate
sprites  from  BASIC by quickly "flipping through" shapes,  using each
shape like a frame from a movie film.

    SPRSAV 0, A$     copy the data (shape) of sprite 0 into A$

    SPRSAV A$, 2     copy the data (shape) in A$ into sprite 2

    SPRSAV 1, 2      copy the data (shape) in sprite 1 to sprite 2


STASH -- (see the DMA command)


SQR -- Square root function

                             SQR (number)

This function returns the SQuare Root of the given numeric expression.
The  numeric  expression must not be negative or an 'ILLEGAL QUANTITY'
error is reported.

               A = SQR(10)     Result is A = 3.16227766


STEP -- See FOR/NEXT/STEP


STOP -- Halt program execution

When  STOP  is  executed,  the  computer immediately stops running the
program  and reports 'BREAK IN LINE xx'.  No variables are cleared and
files are not closed.

This command is usually used while debugging (fixing) a BASIC program,
since it lets you stop at a specific place,  examine variables, change
variables,  and  restart the program where it was halted (see CONTinue
command)  or some other line (see GOTO).  In many cases,  you can even
change  the  program  and  use GOTO to resume execution with variables
and open channels intact.


SWAP -- (see the DMA command)


STR$ -- Get the string representation of a number

                           STR$ (number)

The  STRing  function  returns a string identical to PRINT's output of
the  given  numeric  expression.  See  PRINT for details regarding the
format of numeric output. STR$ is the opposite of VAL.

            A$ = STR$(123)         Result is A$ = " 123"
            A$ = STR$(-123)        Result is A$ = "-123"
            A$ = STR$(.009)        Result is A$ = " 9E-03"


SYS -- Call a ROM routine or user machine language routine

            SYS address [,[a] [,[x] [,[y] [,[z] [,s] ]]]]

This  statement  performs  a call to a machine language routine at the
specified  address  (range 0-65535, $3000-$FFFF)  in a memory bank set
up previously by the BANK command.

The microprocessor's registers are loaded with the values specified in
the  parameters  following  the  address  (if  given)  and a JSR (Jump
SubRoutine)  instruction  is  performed.  When the called routine ends
with an RTS  (ReTurn from Subroutine),  the microprocessor's registers
are   saved  and  control  is  returned  to  the  BASIC  program.  The
microprocessor's registers can be examined with the RREG command.

Because  this command instructs the computer's microprocessor (CPU) to
perform  something,  extreme  care should be taken in its use.  It can
easily  crash the computer if you do something wrong  (press the reset
button to reboot). Also see the BOOT SYS command.

 BANK 128: SYS DEC("FF5C")       Call the Kernel's PHOENIX routine.

 BANK 128: SYS DEC("FF81")       Reset the Screen Editor

 10 BANK 128
 20 BLOAD"user routine",P(DEC("1800"))   Load a user routine
 30 SYS DEC("1800"), areg, xreg          Call it with args in A and X
 40 RREG areg, xreg, , , sreg            Get args back in A, X, and S
 50 carry = (sreg AND 1)                 Get carry flag from S
 60 PRINT "ACCUMULATOR = ";HEX$(areg)    Display registers
 70 PRINT "X REGISTER  = ";HEX$(xreg)
 80 PRINT "CARRY FLAG  = ";carry

See  the  USR  function  for  another  way  to  call  machine language
routines.


TAB -- Space PRINT output

                             TAB (number)

The  TAB  function  is  used  to  format PRINTed data to the screen, a
printer,  or  a  file.  It's  primarily for screen text output, moving
the  cursor  to the specified column (plus one) as long as the current
print position is not already beyond that point  (for example,  if the
current  print  position  is  the  first  column,  TAB(1)  would print
subsequent text beginning in column 2).  If the current print position
is already beyond the column specified by the TAB function, nothing is
done.  For  disk  and  printer output,  TAB works exactly like the SPC
function (see SPC).

A semicolon (';') is always assumed to follow TAB,  even if it appears
at the end of a print line.

   PRINT "TEXT";TAB(10);"HERE"        Result is 'TEXT      HERE'

   PRINT "TEXT";SPC(10);"HERE"        Result is 'TEXT          HERE'

The above examples illustrate the difference between TAB and SPC.  See
also  the  SPC  function.  A better way to format PRINT output is with
PRIUT  USING.  Don't  confuse the TAB function with the TAB character,
CHR$(9),  which  is  used  to  format  data using the programmable TAB
stops.


TAN -- Tangent function

                           TAN (expression)

This function returns the tangent of the numeric expression,  measured
in  radians.  If  the  result  overflows,  TAN(pi/2)  for  example, an
'OVERFLOW' error is reported.

            X = TAN(1)             Result is X=1.55740772

To  get  the  tangent  of  an angle measured in degrees,  multiply the
numeric expression by pi/180.


TEMPO -- Set the tempo (speed) of a PLAY string

                              TEMPO rate

Use  this command to adjust the tempo (speed) of music playback by the
PLAY  command.  The rate determines the duration of a whole note.  The
default is 12, making a whole in 4/4 time last 2 seconds.  The formula
is:
                          duration = 24/rate

The higher the rate, the faster the note. The range is (1-255).


THEN -- See IF/THEN/ELSE


TO -- See FOR/NEXT/STEP. Also used as a subcommand.


TRAP -- Define an BASIC error handler

                          TRAP [line_number]

When  turned on,  TRAP intercepts all BASIC execution error conditions
except 'UNDEF'D STATEMENT ERROR'. Even the STOP key can be TRAPped.

When an error occurs,  BASIC saves the error's location,  line number,
and  error  number.  If TRAP is not set,  BASIC returns to direct mode
and displays the error message and line number.  If TRAP is set, BASIC
performs a GOTO to the line number specified in the TRAP statement and
continues executing.

Your  BASIC  error  handling  routine  can  examine  the error number,
message,  and  the  line number where the error occurred and determine
the proper course of action. The system error words are:

          ER      Error Number
          EL      Error Line (line where the error occurred)
          ERR$()  Error Message

If  ER  is  -1,  then  a BASIC error did not occur.  The error routine
should  check  the  disk status words,  in case they were the cause of
the error:

          DS      Disk Error Number
          DS$     Disk Error Message

Refer to the list of BASIC and Disk error messages in the appendix.

Note that an error in your TRAP routine cannot be trapped.  The RESUME
statement can be used to resume execution -- see RESUME.

TRAP with no line number specified turns off error TRAPping.

          10 TRAP 90                       enable trapping
          20 FOR I=-5 TO 5
          30 PRINT 5/I                     error when I=0
          40 NEXT
          50 TRAP                          turn trapping off
          60 END
          70 :
          90 PRINT ERR$(ER): RESUME NEXT   error routine


TROFF -- Turn off trace mode
TRON  -- Turn on  trace mode

                               TROFF
                               TRON

Trace  mode  is  used  while debugging (fixing) a BASIC program.  TRON
enables tracing,  and TROFF disables tracing.  When the program is run
and  trace  mode  is  on, the line number of the command that is being
executed  is  displayed on the screen.  If there are three commands on
the  line,  the  line number will be displayed three times,  once each
time  one  of the commands is executed.  Trace mode lets you know what
the computer is doing.

Trace  mode  works even when a graphic screen is being displayed,  but
the  line number is still displayed on the text screen so you won't be
able to see it until the graphic screen is turned off. If your program
is  doing  alot  of  PRINT  statements,  the display can seen a little
confusing.

Trace  mode can be set in direct mode to trace the entire program,  or
it  can be turned on and off from within your program to let you trace
only selected portions of the program.

Trace  mode  has  no effect on commands entered in direct (edit) mode.
The NEW command disables trace mode, but RUN and CLR do not.

                             10 FOR I=-5 TO 5
                             15 TRON
                             20 PRINT 5/I
                             25 TROFF
                             30 NEXT


TYPE -- Display the contents of a sequential disk file

              TYPE "filename" [,Ddrive] [<,|ON>Udevice]

Use  this  command to print the contents of a PETSCII data file on the
screen. The file must contain lines no longer than 255 characters long
and terminated by a return character (CHR$(13)). Lines too long result
in a 'STRING TOO LONG' error.

TYPE "readme"    display the contents of the README file on the screen

The  command sequence below will print the contents of the README file
on a CBM serial bus printer in upper/lower case mode.

                OPEN 4,4,7: CMD4: TYPE"readme": CLOSE4


UNTIL -- See DO/LOOP/WHILE/UNTIL/EXIT


USR - Call a user defined machine language function

                           USR (expression)

When  this  function  is used, the program jumps to a machine language
subroutine  whose  starting  address  must be POKEd into system memory
(BANK 128) at address 760 (low byte) and 761 (high byte), or $2F8 hex.
The  floating  point  value of the numeric expression is passed to the
routine  in  the  Floating point ACCumulator (FACC),  and the value to
be returned is taken from the FACC when the routine ends.

If  the  USR  vector  is  not set up prior to making the USR call,  an
'UNDEF'D FUNCTION'  error is reported.  The routine must be located in
the system bank. The BANK command does not affect USR.

Using  this  method  of  calling a machine language routine requires a
fair  amount  of  set  up and a good knowledge of the lower level math
routines built into BASIC. See the SYS command, which is more commonly
used to call a machine language routine.

The  following  program  illustrates  the  basic  steps  required  for
installing a USR routine and calling it:

 10 BANK 128                               System bank for poke & load
 20 UV = DEC("1800")                       Where my routine is
 30 BLOAD "my user routines",P(UV)         Load my routine
 40 POKE DEC("2F8"), UV AND 255, UV / 256  Set up USR address
 50 x = USR(123): PRINT X                  Call my routine with the
                                           the value 123, get back and
                                           print whatever my routine
                                           leaves in FACC

The following program actually works.  It points the USR vector to the
BASIC  math  jump  table  entry for the routine which inverts the sign
of the number in the FACC. Type in positive & negative numbers:

 10 BANK 128                               System bank for poke
 20 POKE DEC("2F8"), DEC("33"), DEC("7F")  Set up USR address
 30 DO: INPUT"SIGNED NUMBER"; N            Get number input
 40 : PRINT USR(N)                         Display USR output
 50 : LOOP UNTIL N=0                       End if user types zero


USING -- See PRINT USING


VAL -- Get the numerical value of a string

                             VAL (string)

The  VALue  function  converts a string into a number.  The conversion
starts  with  the first character and ends at the end of the string or
the first character that is not allowed in normal number input. Spaces
are  ignored.  If  the  first  character  of the string is not a legal
character, a zero is returned.

The  VAL  function  works the same way the INPUT and READ commands do.
VAL is the opposite of STR$.

             X = VAL(" 123")         Result is X =  123
             X = VAL("-123")         Result is X = -123
             X = VAL(" 9E-02")       Result is X = .09


VERIFY -- Compare a program or data in memory with a disk file

         VERIFY "filename" [,device_number [,relocate_flag]]

This  command  is just like a LOAD command,  except instead of putting
the  data  read  from a file into memory,  the computer compares it to
what  is already in memory. If there's any difference at all a 'VERIFY
ERROR' is reported.

The filename  must be given, and pattern matching may be used.  In the
case  of  dual  drive  systems,  the  drive number must be part of the
filename.  If  a  device  number is given,  the file is sought on that
unit,  which  must  be a disk drive.  If a device number is not given,
the default system drive is used. See also DVERIFY.

Note:  If  the  BASIC  program  in  memory  is not located at the same
address  as  the  version  on disk was SAVEd from,  the files will not
match even if the program is otherwise identical.

The relocate_flag is used to VERIFY binary files. If the relocate_flag
is present and non-zero,  the file will be compared to memory starting
at the address stored on disk when the file was SAVEd. The memory bank
used is the bank given in the last BANK statement.  The ending address
is  determined  by  the length of the disk file.  The comparison halts
on  the  first  mismatch  or  at  the end of the file.  The area to be
compared  must  be  confined  to the indicated memory bank. Do not use
the relocate_flag to verify BASIC programs. See also BVERIFY.

                          VERIFY "myprogram"

Good:   SEARCHING FOR 0:myprogram     Bad:   SEARCHING FOR 0:myprogram
        VERIFYING                            VERIFYING
        OK                                   ?VERIFY ERROR

  VERIFY "PROG"        Compares BASIC program in memory to file PROG
                       on the default system disk.

  VERIFY FILE$,DRV     Compares program in memory to a program whose
                       name  is  in  the  variable FILE$ on the unit
                       whose number is in DRV.

  VERIFY "0:PROG",8    Compares memory to BASIC program PROG on unit
                       8, drive 0.

  BANK 128             Compares  a  binary  file  into  memory.  The
  VERIFY "BIN",8,1     address  used  comes from the disk file,  but
                       you must specify the memory bank.


VIEWPORT --     [*** CURRENTLY UNIMPLEMENTED ***]


VOL -- Set audio volume level

                              VOL volume

                  [*** THIS COMMAND WILL CHANGE ***]

This statement sets the volume level for SOUND and PLAY statements.

VOLUME  can  be  set  from  0 to 15, where 15 is the maximum volume. A
volume  of  0  turns  sound  output off.  VOLume affects all 3 voices.
Note that PLAY strings can change the volume, too.


WAIT -- Pause BASIC program until a memory state satisfied

                  WAIT address, and_mask [,xor_mask]

The WAIT statement causes program execution to be suspended until data
at a specified memory location matches a given bit pattern.  It's used
to pause your program until an event occurs.

The  event  could be an I/O state (such as a fire button or peripheral
port  change),  a hardware state (such as the raster position or RS232
status),  or  memory  change  caused  by an interrupt event (such as a
keyboard scan).

The WAIT statement tells the computer to read (PEEK) a memory location
(0-65535)  and  AND  the  value  it  got  with  the number in and_mask
(0-255).  If the result is zero, repeat the operation until the result
is not zero.  This is like the following BASIC instructions,  but much
faster:

  DO: result = PEEK(address): LOOP UNTIL (result AND and_mask) <> 0

This  works  if  the  state  you are WAITing for is non-zero (a one or
"high"  state).  If you want to wait for a zero state (a "low" state),
you need to use the xor_mask option to "flip" the bits of the result.

Note  that  it's  possible  to "hang" your program indefinitely if the
state you are waiting for never happens or you specify the wrong data.
Press the STOP and RESTORE keys at the same time to get control back.

Be  sure  to use the BANK command before you tell the computer to WAIT
to specify  which 64K memory bank the address is in.  Note that a BANK
number greater than 127 (i.e., a bank number with the most significant
bit  set)  must  be  used to address an I/O location,  such as the VIC
chip. Refer to the system memory map for details.

    10 BANK 128                     Wait for the VIC raster to be
    20 WAIT DEC("D011"), 128        offscreen (want RC8 = 1)

    10 BANK 128                     Wait for the VIC raster to be
    20 WAIT DEC("D011"), 128, 128   onscreen (want RC8 = 0)

    10 BANK 128
    20 WAIT DEC("D3"), 1            Wait for user to press <SHIFT> key
    30 WAIT DEC("D3"), 2            Wait for user to press <C=> key
    40 WAIT DEC("D3"), 4            Wait for user to press <CTRL> key
    50 WAIT DEC("D3"), 8            Wait for user to press <ALT> key


WHILE -- See DO/LOOP/WHILE/UNTIL/EXIT


WIDTH --         [*** CURRENTLY UNIMPLEMENTED ***]


WINDOW -- Set a text window

  WINDOW  left_column, top_row, right_column, bottom_row [,clear]

This  command defines a logical text screen window.  All text I/O will
be  confined  to this window.  The row parameters must be in the range
(0-24),  and  the  column  parameters  must be in the range (0-79) for
80-column screens or (0-39) for 40-column screens.  The parameters are
always  referenced  to the physical screen  (i.e., you cannot define a
window  within a window).  If the clear flag is given,  the new window
area will be cleared after it's set up.

Use the RWINDOW function to get the current window size.

You  are  responsible  for  saving  and  restoring  screen data in all
windows because the WINDOW command simply sets the window margins. The
WINDOW  command  does  not  draw  a border around a window.  All color
commands  and  screen  modes (such as scroll disable, TAB stops, etc.)
are global.

Two  consecutive  "home"  characters  will reset the window definition
back to the physical screen.

   WINDOW 0,0,39,24          Define  a  window  in  80-column  mode
                             that is the left half of the screen.

   WINDOW 40,0,79,24         Define  a  window  in  80-column  mode
                             that is the right half of the screen.

   WINDOW 0,0,79,12          Define  a  window  in  80-column  mode
                             that is the top half of the screen.

   WINDOW 0,13,79,24         Define  a  window  in  80-column  mode
                             that is the bottom half of the screen.

   WINDOW 20,6,59,12,1       Define  a  window in 80-column mode in
                             the center of the screen and clear it.
                             The  window  is 12 characters high and
                             40 characters wide.

   PRINT CHR$(19)CHR$(19);   Reset  the  window back to full screen
                             in either 40 or 80-column mode and put
                             the cursor in top left corner.


XOR -- Exclusive-Or function

                         XOR (number,number)

The  XOR  function returns a numeric value equal to the logical XOR of
two numeric expressions, operating on the binary value of the unsigned
16-bit integers in the range (0 to 65535).  Numbers outside this range
result in an 'ILLEGAL QUANTITY' error.

                X = XOR(4,12)           Result is X= 8
                X = XOR(2,12)           Result is X=14



3.1.4. VARIABLES

The C64DX uses three types of variables in BASIC:

                      floating point          X
                      integer                 X%
                      string                  X$

     Normal  NUMERIC VARIABLES,  also called floating point variables,
can have any from up to nine digits of accuracy. When a number becomes
larger  than  nine  digits  can show,  as in +10 or -10,  the computer
displays it in scientific notation form, with the number normalized to
1  digit  and  eight decimal places,  followed by the letter E and the
power  of  ten  by  which the number is multiplied.  For example,  the
number 12345678901 is displayed as 1.23456789E+10.

     INTEGER VARIABLES  can  be used when the number is a signed whole
number from +32767 to -32768.  Integer data is a number like 5, 10, or
-100.  Integers  take  up  less  space  than floating point variables,
particularly when used in an array.

     STRING VARIABLES  are  those  used for character data,  which may
contain  numbers,  letters,  and any other character that the computer
can make. An example of string data is "Commodore C64DX".

     VARIABLE NAMES may consist of a single letter,  a letter followed
by  a  number,  or  two  letters.  Variable names may be longer than 2
characters,  but  only  the  first two are significant.  An integer is
specified  by  using  the  percent  (%)  sign after the variable name.
String variables have a dollar sign ($) after their names.

                              EXAMPLES:

                 Numeric Variable Names: A,  A5 , BZ
                 Integer Variable Names: A%, A5%, BZ%
                 String Variable Names : A$, A5$, BZ$

     ARRAYS are lists of variables with the same name,  using an extra
number  (or  numbers)  to specify an element of the array.  Arrays are
defined using the DIM statement,  and may be floating point,  integer,
or  string  variable arrays.  The array variable name is followed by a
set  of  parentheses  ()  enclosing  the number of the variable in the
list.

                               EXAMPLE:

                        A(7), BZ%(11), A$(87)

     Arrays can have more than one dimension.  A two dimensional array
may  be  viewed  as having  rows  and  columns,  with the first number
identifying  the  row and the second number identifying the column (as
if specifying a certain grid on the map).

                               EXAMPLE:

                     A(7,2), BZ%(2,3,4), Z$(3,2)

     RESERVED  VARIABLE  NAMES  are names that are reserved for use by
the computer,  and may not be used for another purpose.  These are the
variables DS, DS$, ER, ERR$, EL, ST, TI, and TI$.  KEYWORDS such as TO
and IF or any other names that contain KEYWORDS,  such as RUN, NEW, or
LOAD cannot be used.

     ST  is  a  status  variable  for input and output  (except normal
screen/keyboard operations). The value of ST depends on the results of
the last I/O operation.  In general,  if the value of ST is 0 then the
operation was successful.

     TI and TI$ are variables that relate to the real-time clock built
into  the C64DX.  The system clock is reset to zero when the system is
powered up or reset, and can be changed by the user or a program.

  TI$="hh:mm:ss.t"   Allows  optional colons to delimit parameters and
                     allows input to be abbrieviated  (eg., TI$="h:mm"
                     or   even   TI$=""),   defaulting   to  "00"  for
                     unspecified parameters. 24-hour clock (00:00:00.0
                     to 23:59:59.9).

  TI                 24-hour TOD converted into tenths of seconds.

     The  value  of the clock is lost when the computer is turned off.
It starts at zero when the computer is turned on, and is reset to zero
when the value of the clock exceeds 23:59:59.9.

     The variable DS reads the disk drive command channel, and returns
the  current  status  of the drive.  To get this information in words,
PRINT  DS$.  These  status  variables are used after a disk operation,
like DLOAD or DSAVE, to find out why the error light on the disk drive
is blinking.

     ER,  EL,  and ERR$ are variables used in error trapping routines.
They  are  usually  only useful within a program.  ER returns the last
error encountered since the program was RUN.  EL is the line where the
error  occurred.  ERR$  is a function that allows the program to print
one of the BASIC error messages.  PRINT ERR$(ER) prints out the proper
error message.



3.1.5. OPERATORS

     The  BASIC OPERATORS  include ARITHMETIC, RELATIONAL, and LOGICAL
OPERATORS. The ARITHMETIC operators include the following signs:

                  + addition
                  - subtraction
                  * multiplication
                  / division
                  ^ raising to a power (exponentiation)

     On a line containing more than one operator, there is a set order
in  which  operations  always  occur.  If  several  operators are used
together,   the   computer   assigns   priorities  as  follows.  First
exponentiation,  then  multiplication and division, and last, addition
and  subtraction.  If  two  operators  have  the  same  priority, then
calculations  are  performed  in  order  from left to right.  If these
operations are to occur in a different order, BASIC 10.0 allows giving
a  calculation  a  higher  priority  by placing parentheses around it.
Operations enclosed in parentheses will be calculated before any other
operation.  Make  sure that the equations have the same number of left
and  right  parentheses,  or a SYNTAX ERROR message is posted when the
program is run.

     There are also operators for equalities and inequalities,  called
RELATIONAL  operators.  Arithmetic operators always take priority over
relational operators.

              =            is equal to
              <            is less than
              >            is greater than
              <= or =<     is less than or equal to
              >= or =>     is greater than or equal to
              <> or ><     is not equal to

     Finally,  there  are three LOGICAL operators, with lower priority
than both arithmetic and relational operators:

              AND
              OR
              NOT

     These  are most often used to join multiple formulas in IF...THEN
statements.  When  they  are used with arithmetic operators,  they are
evaluated last  (i.e.,  after + and -).  If the relationship stated in
the expression is the true the result is assigned an integer of -1 and
if false an integer of 0 is assigned. There is also an XOR function.

                              EXAMPLES:

  IF A=B AND C=D THEN 100         requires both A=B & C=D to be true
  IF A=B OR C=D THEN 100          allows either A=B or C=D to be true
  A=5:B=4:PRINT A=B               displays  0
  A=5:B=4:PRINT A>3               displays -1
  PRINT 123 AND 15:PRINT 5 OR 7   displays 11 and 7



3.1.6. ERROR MESSAGES


3.1.6.1. BASIC ERROR MESSAGES

     The  following  error  messages  are  displayed  by BASIC.  Error
messages  can  also  be displayed with the use of the ERR$() function.
The  error  number refers only to the number assigned to the error for
use with this function.  In direct mode,  DOS error messages (DS$) are
automatically  displayed. They are described in the section after this
one.

ERROR#     ERROR NAME                       DESCRIPTION
----------------------------------------------------------------------
  1  TOO MANY FILES         There is a limit of 10 files OPEN at one
                            time.

  2  FILE OPEN              An attempt was made to open a file using
                            the number of an already open file.

  3  FILE NOT OPEN          The file number specified in an I/O
                            statement must be opened before use.

  4  FILE NOT FOUND         No file with that name exists on the
                            specified drive.

  5  DEVICE NOT PRESENT     The required I/O device not available.

  6  NOT INPUT FILE         An attempt made to read data from a file
                            that was opened for writing.

  7  NOT OUTPUT FILE        An attempt was made to write data to a
                            file that was opened for reading.

  8  MISSING FILE NAME      Filename was missing in command.

  9  ILLEGAL DEVICE NUMBER  An attempt was made to use a device
                            improperly (SAVE to the screen, etc) or
                            an illegal device number was specified.

 10  NEXT WITHOUT FOR       Either loops are nested incorrectly, or
                            there is a variable name in a NEXT
                            statement that doesn't correspond with
                            one in FOR.

 11  SYNTAX ERROR           A statement is unrecognizable by  BASIC.
                            This could be  because of missing or
                            extra parenthesis, parameters, delimiters,
                            or a misspelled keyword.


 12  RETURN WITHOUT GOSUB   A RETURN statement was encountered when no
                            GOSUB statement was active.

 13  OUT OF DATA            A READ statement was encountered with no
                            DATA left unREAD.

 14  ILLEGAL QUANTITY       A number used as an argument is  outside
                            the allowable range (too big or too small)

 15  OVERFLOW               The result of a computation is larger than
                            the largest number allowed (1.701411834E+38)

 16  OUT OF MEMORY          There is not enough memory for the program,
                            or variables, or there are too many DO, FOR
                            or GOSUB statements in effect.

 17  UNDEF'D STATEMENT      A line number referenced doesn't exist.

 18  BAD SUBSCRIPT          The program tried to reference an element
                            of an array out of the range specified by
                            a DIM statement, a missing DIM statement
                            or a mistyped function name.

 19  REDIM'D ARRAY          An array can only be DIMensioned once.

 20  DIVISION BY ZERO       Division by zero is illegal.

 21  ILLEGAL DIRECT         Command is only allowed to be used in a
                            program.

 22  TYPE MISMATCH          A numeric variable was used in place of
                            a string variable or vice versa.

 23  STRING TOO LONG        An attempt was made to assign more than
                            255 characters to a string, or enter more
                            than 160 characters from the keyboard, or
                            to input more than 255 characters from a
                            file.

 24  FILE DATA              The wrong type of data was read from a
                            file.

 25  FORMULA TOO COMPLEX    An expression is too complicated for BASIC
                            to process all at one time. Break it into
                            smaller pieces or use fewer parentheses.

 26  CAN'T CONTINUE         The CONT command does not work if the
                            program was not RUN, there was an error
                            or a line has been edited.

 27  UNDEFINED FUNCTION     An attempt was made to use a user defined
                            function that was never defined.

 28  VERIFY                 The program on disk does not match the
                            program in memory.

 29  LOAD                   There was a problem loading.

 30  BREAK                  The program was halted by the STOP key or
                            a STOP statement.

 31  CAN'T RESUME           A RESUME statement was encountered without
                            a TRAP in effect, or an error occurred in
                            the trap handler itself.

 32  LOOP NOT FOUND         The program encountered a DO statement and
                            cannot find the corresponding LOOP.

 33  LOOP WITHOUT DO        A LOOP was encountered without a DO
                            statement active.

 34  DIRECT MODE ONLY       A command was used in a program that can
                            only be used in direct mode.

 35  NO GRAPHICS AREA       A graphics command was used before a
                            graphics screen was defined and opened.

 36  BAD DISK               A BOOT SYS command failed because the disk
                            could not be read.

 37  BEND NOT FOUND         A BEND statement not found for BEGIN.

 38  LINE NUMBER TOO LARGE  A line number cannot exceed 64000.

 39  UNRESOLVED REFERENCE   Renumber failed because a referenced line
                            number does not exist.

 40  UNIMPLEMENTED COMMAND  The given command is not currently
                            implemented in this computer.

 41  FILE READ              There was a problem reading data from a
                            disk file. Similar to LOAD ERROR.


3.1.6.2. DOS ERROR MESSAGES

     The  following error messages are returned through the DS and DS$
variables.  If  a disk command is type in direct mode,  these messages
will  be displayed automatically.  NOTE: DOS message numbers less than
20 are advisory and are not necessarily errors.  DOS messages may vary
slightly depending upon the drive model.  Refer to your DOS manual for
details.

ERROR #                           DESCRIPTION
------- --------------------------------------------------------------
  00:   OK (no error)

  01:   FILES SCRATCHED (not an error)
        The following number (track) tells how many files were deleted
        by the scratch command.

  02:   PARTITION SELECTED (not an error)
        The requested disk partition (subdirectory) has been selected.

  03:   FILES LOCKED
        The requested file(s) have been locked.

  04:   FILES UNLOCKED
        The requested file(s) have been unlocked.

  05:   FILES RESTORED
        The requested file(s) have been recovered (undeleted).

  20:   READ ERROR (block header not found)
        The  disk  controller  is  unable  to locate the header of the
        requested  data  block. Caused by an illegal sector number, or
        the header has been destroyed.

  21:   READ ERROR (no sync character)
        The  disk  controller  is  unable to detect a sync mark on the
        desired track.  Caused by misalignment of the read/write head,
        no  diskette  is present,  or unformatted or improperly seated
        diskette. Can also indicate a hardware failure.

  22:   READ ERROR (data block not present)
        The  disk  controller  has  been requested to read or verify a
        data block that was not properly written. This error occurs in
        conjunction  with  the BLOCK commands and indicates an illegal
        track and/or sector request.

  23:   READ ERROR (checksum error in data block)
        This  error message indicates that there is an error in one or
        more  of  the data bytes.  The data has been read into the DOS
        memory,  but  the  checksum  over  the data is in error.  This
        message may also indicate grounding problems.

  24:   READ ERROR (byte decoding error)
        The  data  or  header has been read into the DOS memory, but a
        hardware  error has been created due to an invalid bit pattern
        in  the  data  byte.  This message may also indicate grounding
        problems.

  25:   WRITE ERROR (write-verify error)
        This message is generated if the controller detects a mismatch
        between the written data and the data in the DOS memory.

  26:   WRITE PROTECT ON
        This  message  is  generated  when  the  controller  has  been
        requested to write a data block while the write protect switch
        is depressed.

  27:   READ ERROR
        This  message  is  generated  when  a checksum error is in the
        header.

  28:   WRITE ERROR
        This error message is generated when a data block is too long.

  29:   DISK ID MISMATCH
        This  message  is  generated  when  the  controller  has  been
        requested to access a diskette which has not been initialized.
        The message can also occur if a diskette has a bad header.

  30:   SYNTAX ERROR (general syntax)
        The  DOS  cannot  interpret  the  command  sent to the command
        channel.  Typically,  this  is  caused by an illegal number of
        file names,  or patterns are illegally used.  For example, two
        file names appear on the left side of the COPY command.

  31:   SYNTAX ERROR (invalid command)
        The DOS does not recognize the command. The command must start
        in the first position.

  32:   SYNTAX ERROR (invalid command)
        The command sent is longer than 58 characters.

  33:   SYNTAX ERRROR (invalid file name)
        Pattern  matching  is  invalidly  used  in  the  OPEN  or SAVE
        command.

  34:   SYNTAX ERROR (no file given)
        The  file name was left out of the command or the DOS does not
        recognize it as such.

  39:   SYNTAX ERROR (invalid command)
        This  error  may  result  if  the  command sent to the command
        channel (secondary address 15) is unrecognized by the DOS.

  40:   UNIMPLEMENTED COMMAND
        Command is not implemented at this time.

  41:   FILE READ
        The file cannot be read.

  50:   RECORD NOT PRESENT
        Result  of disk reading past the last record through INPUT# or
        GET# commands.  This message will also occur after positioning
        to  a  record  beyond end_of_file  in a relative file.  If the
        intent is to expand the file by adding the new record  (with a
        PRINT# command),  the error message may be ignored.  INPUT and
        GET  should  not  be  attempted  after  this error is detected
        without first repositioning.

  51:   OVERFLOW IN RECORD
        PRINT#  statement  exceeds  record  boundary.  Information  is
        truncated. Since the carriage return which is sent as a record
        terminator  is  counted in the record size,  this message will
        occur  if  the  total characters in the record  (including the
        final carriage return) exceeds the defined size.

  52:   FILE TOO LARGE
        Record  position  within  a  relative file indicates that disk
        overflow will result.

  53:   BIG RELATIVE FILES DISABLED

  60:   WRITE FILE OPEN
        This  message is generated when a write file that has not been
        closed is being opened for reading.

  61:   FILE NOT OPEN
        This  message  is generated when a file is being accessed that
        has  not  been opened in the DOS.  Sometimes,  in this case, a
        message is not generated: the request is simply ignored.

  62:   FILE NOT FOUND
        The requested file does not exist on the indicated drive.

  63:   FILE EXISTS
        The  file name of the file being created already exists on the
        diskette.

  64:   FILE TYPE MISMATCH
        The  requested  access mode is not possible using the filetype
        given.

  65:   NO BLOCK
        The  sector  you  tried  to  allocate with the B-A command was
        already allocated.  The track and sector numbers hold the next
        higher,  available track  and  sector.  If the track number is
        zero, no higher sectors are free (try a lower track & sector).

  66:   ILLEGAL TRACK AND SECTOR
        The  DOS  has  attempted to access a track or block which does
        not  exist  in  the  format  being  used.  This may indicate a
        problem reading the pointer of the next block.

  67:   ILLEGAL SYSTEM T OR S
        This  special  error message indicates an illegal system track
        or sector.

  70:   NO CHANNEL
        The requested channel is not available, or all channels are in
        use.  A  maximum of five sequential files may be opened at one
        time  to  the  DOS. Direct access channels may have six opened
        files.

  71:   DIRECTORY ERROR
        The BAM is corrupted. Try initializing the disk.

  72:   DISK FULL
        Either the blocks on the diskette are used or the directory is
        at  its  entry  limit.  DISK  FULL is sent when two blocks are
        available  to  allow  the current file to be closed before its
        data is lost.

  73:   DOS MISMATCH (also the powerup message)
        Initially  given  at  powerup  to  identify the drive. On some
        drives  this  message  is  given  as  an error to indicate the
        media was formatted by an incompatible DOS.

  74:   DRIVE NOT READY
        An  attempt  has  been  made  to  access the Floppy Disk Drive
        without any diskette present.

  75:   FORMAT ERROR

  76:   CONTROLLER ERROR
        The DOS has determined that the hardware is malfunctioning.

  77:   SELECTED PARTITION ILLEGAL
        An  attempt  was made to access a partition as a subdirectory,
        but  it  has  no directory track or does not meet the criteria
        of a directory partition.

  78:   DIRECTORY FULL
        There is no more room in the directory sector for another file
        entry. Delete a file to make room, or change disks.

  79:   FILE CORRUPTED
        The DOS has determined that a file is bad, probably having bad
        links.  Prepare  a  new  disk  and  copy the good files to it.
        Could be the result of an unsuccessful file recovery.



3.2. MACHINE LANGUAGE MONITOR


3.2.1. INTRODUCTION

     The  MONITOR is a built in machine language program that lets the
user  easily  write  machine  language  programs.  The  C64DX  MONITOR
includes a machine language monitor, an assembler, and a disassembler.

     Machine  language  programs  written using the MONITOR can run by
themselves,  or be used as very fast 'subroutines' for BASIC programs.
Care  must  be  taken  to  position  the assembly language programs in
memory  so  that  the  BASIC  program  does not overwrite them and the
proper   memory   is   in  context  at  all  times  (including  during
interrupts).


3.2.2. MONITOR COMMANDS

A       ASSEMBLE        - Assemble a line of 4502 code
C       COMPARE         - Compare two sections of memory
D       DISASSEMBLE     - Disassemble a line of 4502 code
F       FILL            - Fill a section of memory with a value
G       GO              - Start execution at specified address
H       HUNT            - Find specified data in a section of memory
L       LOAD            - Load a file from disk
M       MEMORY          - Dump a section of memory
R       REGISTERS       - Display the contents of the 4502 registers
S       SAVE            - Save a section of memory to a disk file
T       TRANSFER        - Transfer memory to another location
V       VERIFY          - Compare a section of memory with a disk file
E       EXIT            - Exit Monitor mode

.       <period>        - Assembles a line of 4502 code
>       <greater-than>  - Modifies memory
;       <semicolon>     - Modifies register contents
@       <at sign>       - Display disk status

$       <hex>           - Display hex, decimal, octal, and binary value
+       <decimal>
&       <octal>
%       <binary>

The MONITOR accepts binary,  octal, decimal and hexadecimal values for
any  numeric field.  Numbers prefixed by one of the characters $ + & %
are interpreted as base  16,  10, 8, or 2 values respectively.  In the
absence of a prefix, the base defaults to hexadecimal always.

The  assembler  will use the base page form of an instruction wherever
possible  unless the address field is preceded by extra zeros to force
the absolute form (except binary notation).

The most significant byte of a 24-bit (3-byte) address field specifies
the  memory  BANK  to  implement  at  the  time  the  given command is
executed.  BANK bytes with the MSB set  (i.e., banks greater than $7F)
mean "use the current system configuration", which always includes the
I/O area. If a BANK is not specified, BANK 0 is assumed.

  BANK 00         internal RAM bank 0 (System, BASIC program)
  BANK 01         internal RAM hank 1 (DOS, BASIC vars, color bytes)
  BANK 02         internal ROM bank 0 (DOS, C64 mode, CHRSETS)
  BANK 03         internal ROM bank 1 (Monitor, C65 mode)

  BANK 04-07      reserved for future expansion

  BANK 08-7F      expansion RAM (graphic screens, RAM disk, etc.)

  BANK 80-FF      MSB set means current config & I/O

The  monitor  supports  the editor autoscroll feature for memory dumps
(forwards and backwards) and disassemblies (forward disassembly only).

To send dump output to a printer, from BASIC open a CMD channel to the
printer and enter the monitor (OPEN 4,4: CMD4: MONITOR). Give the dump
command desired; output will be to the printer.


3.2.3. MONITOR COMMAND DESCRIPTIONS

COMMAND:       A
PURPOSE:       Enter a line of assembly code.
SYNTAX:        A <address> <mnemonic> <operand>

<address>      A number indicating the location in memory to place the
               assembled binary code.

<mnemonic>     A 4502 assembly language mnemonic, eg., LDA

<operand>      The operand,  when required, can be of any of the legal
               addressing modes.

A  <RETURN>  is used to indicate the end of the assembly line.  If are
any errors on the line,  a question mark is displayed to an error, and
the cursor  moves to the next line.  The screen can be used to correct
the error(s) on that line.

As each line is entered,  the machine code is written to the specified
address and the line is automatically disassembled.

Base  page  and  relative  addresses  are calculated for you,  and the
appropriate  word  or  byte  relative  mode selected automatically. To
force an absolute addressing mode, supply leading zeros if necessary.

                           .A 1800 LDX #$00
                           .A 1802

NOTE: A period (.) is equal to the ASSEMBLE command.

                           . 1900 LDA #$23


COMMAND:        C
PURPOSE:        Compare two areas of memory
SYNTAX:         C <address_1> <address_2> <address_3>

<address_1>     A number indicating the start of the area of memory to
                compare against.

<address_2>     A number indicating the end of the area of  memory  to
                compare against.

<address_3>     A number indicating the start of  the  other  area  of
                memory to compare with.

The  following example compares $8000-$9FFF in bank 0 with $8000-$9FFF
in  bank  1.  Addresses of data that does not match are printed on the
screen.

                          C 8000 9FFF 18000


COMMAND:       D
PURPOSE:       Disassemble machine code
SYNTAX:        D [address_1 [address_2] ]

<address_1>    A number setting the address to start the disassembly.

<address_2>    An optional ending address of code to be disassembled.

The output of the disassembly is the same as that of an assembly, only
preceded by a comma instead of an A or period. The object code is also
displayed.  Relative addresses in the disassembly are displayed as the
16-bit destination.

A  disassembly  listing  can be modified using the screen editor.  Any
changes  to  the  mnemonic  or  operand  on  the screen,  then hit the
<RETURN>.   This   enters   the  line  and  calls  the  assembler  for
instructions. The object code cannot be modified this way.

A  disassembly  can  be  paged.  Typing a D<RETURN> causes the next of
disassembly  to  be displayed. The autoscroll feature works in forward
mode  only,  because backwards disassembly is not possible because all
256 opcodes are defined in the 4502 processor.

The following example disassembles from ROM bank 3:

                     D 3F000 3F005
                     . 03F000 A9 09      LDA #$09
                     . 03F002 A0 FF      LDY #$FF
                     . 03F004 18         CLC
                     . 03F005 86 C2      STX $C2

Note that banks wrap to the next higher bank number.


COMMAND:        F
PURPOSE:        Fill a range of locations with a specified byte.
SYNTAX:         F <address_1> <address_2> <byte>

<address_1>     The first location to fill with the <byte>.

<address_2>     The last location to fill with the <byte>.

<byte>          The byte to fill with

This  command  is useful for initializing data structures or any other
RAM area.

                           F 00600 007FF 00

Fills memory locations from $0600 to $07FF (RAM-0) with $00. Note that
banks  wrap to the next higher bank number.  The maximum area that can
be filled at one time is 64K, limited by the DMA device.


COMMAND:        G
PURPOSE:        Perform a JMP to a specified address
SYNTAX:         G <address>

<address>       The address where execution  is  to  start.  When  the
                address is not  specified,  execution  begins  at  the
                current  PC.  (The current PC can be viewed or changed
                with the R command.)

The  GO  command loads the processor's registers (displayable by the R
command)  and  performs  a  JMP  to  the  specified  starting address.
Caution  is recommended in using the GO command.  To return to MONITOR
mode  after  performing  a GO command,  a BRK instruction must end the
called  routine.  Also,  the  BANK  specified  must  be able to handle
interrupts  (note  that  BANK  bytes  less than $80 do NOT include the
operating system or I/O space).

                               G FFC800

JuMPs to address $C800 in bank $FF (system configuration).


COMMAND:        H
PURPOSE:        Hunt through memory within a specified range  for  all
                occurences of a set of bytes.
SYNTAX:         H <address_1> <address_2> <data>

<address_1>     Address to start at

<address_2>     Last address

<data>          Data  to  search  for.  May  be a number,  sequence of
                numbers, or a PETSCII string.

                      H 02000 0FFFF 46 52 45 44

Hunts  for  the  series  of  bytes $46, $52, $45, $44 in memory bank 0
beginning  at  address  $2000  and  ending at $FFFF.  The addresses of
matches is displayed.

                          H 0200 0FFFF 'FRED

Hunts  for the PETSCII string following an apostrophe. Note that banks
wrap to the next higher bank number.


COMMAND:        L
PURPOSE:        Load a file from disk.
SYNTAX:         L <"filename"> [,device [,load_address] ]

<"filename">    Is a filename in quotes.

[device]        Is a number indicating the device to load from.

[load_address]  Optional load address.  If  not  given,  the  file  is
                loaded  into  memory  at  the 16-bit address stored on
                disk (always RAM bank 0).

The  LOAD command causes a file to be loaded into memory.  If the load
address (including BANK) is given, the data is placed there. Otherwise
the  file  is  loaded  into  RAM  bank  0  at  the 16-bit load address
specified  by  the  first  two  bytes read from the PRG (program) type
file. An error occurs if a load overflow the specified bank.

                             L "filename"

Loads  "filename"  from  default  system  drive into RAM bank 0 at the
address read from the file.

                        L "filename",+10,80000

Loads  "filename"  from  drive 10 (notice you must specify decimal for
the  drive  number,  or use hex equivalent) into expansion memory bank
8  at  address  $0000.  Note  that spaces between parameters after the
filename are not permitted.


COMMAND:        M
PURPOSE:        Dump a section of memory in hex and PETSCII.
SYNTAX:         M [address_1 [address_2] ]

[address_1]     Starting address of memory dump.  If omitted, one page
                is displayed starting from the last address used.

[address_2]     Ending address of memory dump.  If  omitted,  one page
                is displayed starting at address_1.

Memory  dump  width  is sized to 40 or 80 columns,  depending upon the
text screen width.  All data is displayed in hexadecimal and  followed
by a PETSCII interpretation of the data in reverse field (non-printing
characters appear as periods).

The autoscroll keys will scroll the dump forwards or backwards. Paging
is also possible by typing M<RETURN>.

The hex field of dump can be edited,  and memory will be updated after
a <RETURN> is typed on the edited line.

               M 29000 2900C

               >029000 3C 66 6E 6E 60 62 3C 00 :<FNN-B<.
               >029008 46 41 49 54 20 4C 55 58 :FAIT LUX


COMMAND:        R
PURPOSE:        Display "shadow" 4502  registers.  The  PC  (address),
                SR (status), A,X,Y,Z registers, and SP (stack pointer)
                are displayed.
SYNTAX:         R

                       R
                           PC   SR AC XR YR SP
                       ; BA1234 00 00 00 00 FB

The  address  field  contains  the  8-bit bank plus the 16-bit segment
address.  The  register  dump  can be edited by changing any field and
pressing return. The data is used by the G (JMP) and J (JSR) commands.


COMMAND:        S
PURPOSE:        Save a section of memory in a disk file.
SYNTAX:         S <"filename">,<device>,<address_1>,<address_2>

<"filename">    Is a filename in quotes.

<address_1>     Starting address of memory to be saved.

<address_2>     Ending address PLUS ONE of memory to be saved.

The  SAVE  command  creates  a PRG (program) type file and copies data
into it from the specified memory area. All parameters are required.

                      S "filename",8,A0000,AFFFF

Saves  expansion  bank  A  in "filename" on drive 8  (you must specify
decimal  for the drive number,  or use hex equivalent).  The last byte
at $FFFF will not be saved.  Note that spaces between parameters after
the  filename  are not permitted.  The 16-bit segment address is saved
as the first two bytes of the file, but the BANK address is not saved.

The BANK wraps automatically to the next higher bank number,  but note
that LOAD is restricted to one bank, 64K bytes maximum.


COMMAND:        T
PURPOSE:        Transfer (copy) memory from one memory area to another
SYNTAX:         T <address_1> <address_2> <address_3>

<address_1>     Starting address of data to be copied.

<address_2>     Ending address of data to be copied.

<address_3>     Starting address of new location to copy data to.

Data can be copied forwards or backwards to any location,  even within
the  source  range  (eg.,  shift data up or down one byte) without any
problem.  An  automatic  compare  is  performed  for  each  byte,  and
mismatches displayed on the screen.

Because  of  the  compare feature,  it's not recommended you use the T
command  to  copy  data  into  write-only  registers (the palette, for
example). It works, but all the compares will fail.

                         T 32000 3BFFF 82000

Copies BASIC ROM area to expansion RAM.


COMMAND:        V
PURPOSE:        Verify (compare) a disk file with the memory contents.
SYNTAX:         V <"filename"> [,device [,load_address] ]

<"filename">    Is a filename in quotes.

[device]        Is a number indicating the device the file is on.

[load_address]  Optional  load  address.  If  not  given,  the file is
                compared  to  memory  at  the 16-bit address stored on
                disk (always RAM bank 0).

The Verify command causes a file to be read and compared to memory. If
the  load  address  (including  BANK)  is  given,  the  data  read  is
compared  to  data  there.  Otherwise the data read is compared to RAM
bank  0  at  the  16-bit load address specified by the first two bytes
of  the PRG (program) type file.  If there is a mismatch,  the message
'VERIFYING ERROR'  is  displayed.  If  the  data  matches,  nothing is
displayed.  An  error  occurs  if  the  compare  address overflows the
specified bank.

                             V "filename"

Compares "filename" from the default system drive to RAM bank 0 at the
address read from the file.

                        V "filename",+10,80000

Compares "filename" from drive 10 (notice you must specify decimal for
the drive number, or use hex equivalent) to expansion memory bank 8 at
address   $0000.   Note  that  spaces  between  parameters  after  the
filename are not permitted.


COMMAND:        X
PURPOSE:        Exit to BASIC
SYNTAX:         X


COMMAND:        >               (greater than)
PURPOSE:        Pokes data (1 to 16 bytes) into memory
SYNTAX:         > <address>  [byte]...

<address>       Address to start "poking" or displaying

[byte]          Data to be "poked".  If not given,  nothing is changed
                and   the   memory   at  that  location  is  "peeked".
                Successive bytes are poked into successive locations.


COMMAND:        @               (at sign)
PURPOSE:        Disk operation: send command, display directory,status
SYNTAX:         @ [device] [,command]

[device]        Disk device number

[command]       Optional command (see DOS manual for specific commands)

This  command  can  be  used to read a drive's status message,  send a
drive a DOS command, or display a disk directory.

        @               displays status of default system drive
        @9              displays status of drive 9
        @+10  or @A     displays status of drive 10

        @,$             displays directory of default drive
        @9,$            displays status of drive 9
        @,S0:*=SEQ      displays all SEQ type files
        @,S0:FILE       sends command to delete file "FILE"



3.3. EDITOR

3.3.1. EDITOR ESCAPE SEQUENCES

This  section  contains  a definition of the escape sequences that are
present in the C64DX and a brief description of what each does.

ESCape  sequences  are  given  by  hitting  the  <ESCAPE> key and then
another   key.  In  PRINT  strings,  escape  sequences  are  given  by
printing  the escape character CHR$(27) followed by another character.
In  either  case,  the  "other"  character  is  defined  as one of the
following:

KEY  FUNCTION
---  ----------------------------------------------------

 @   Clear from cursor to end of screen
 A   Enable auto-insert mode
 B   Set bottom of screen window at cursor position
 C   Disable auto-insert mode (set overwrite mode)
 D   Delete current line
 E   Set cursor to non-flashing mode
 F   Set cursor to flashing mode
 G   Enable bell (control-G)
 H   Disable bell
 I   Insert line
 J   Move to start of current line
 K   Move to end of current line
 L   Enable scrolling
 M   Disable scrolling
 N   Normal screen fields        [not implemented on C64DX]
 O   Cancel insert, quote, reverse, underline & flash modes
 P   Erase from cursor to start of current line
 Q   Erase from cursor to end of current line
 R   Set screen to reverse video [not implemented on C64DX]
 S   Set bold attribute (VIC-III colors 16-31)
 T   Set top of screen window at cursor position
 U   Unset bold attibute
 V   Scroll up
 W   Scroll down
 X   Swap 40/80 column display output device
 Y   Set default tab stops (8 spaces)
 Z   Clear all tab stops
 [   Set monochrome display (disable attributes)
 /   Cancel insert, quote, rvs, ul & flash modes
 ]   Set color display (enable attributes)


3.3.2. EDITOR CONTROL CODES

This  section  contains  a  definition  of  the control codes that are
present in the C64DX and a brief description of what each does.

Control codes are given by pressing the <CTRL> key at the same time as
another key. In PRINT strings, control codes are given by printing the
control  character  with  the  CHRS()  function.  Control codes appear
within  quoted  strings  as reverse field characters. In any case, the
control characters are:

CHR$    KEYBOARD
VALUE   CONTROL    FUNCTION
-----   --------   ----------------------------------------------
2       B          Underline on
7       G          Bell tone
9       I          Forward TAB
10      J          Line feed
11      K          Disable case change <shift>C= key (was code 9)
12      L          Enable case change <shift>C= key  (was code 8)
14      N          Set display upper/lower case mode
15      O          Flash on
17      Q          Cursor down
18      R          Reverse on
19      S          Home cursor
20      T          Delete previous character
21      U          Backup word
23      W          Advance word
24      X          Tab set/clear
26      Z          Backup TAB
27      [          Escape character
29      ]          Cursor right

Shifted codes
---------------------------------------------------------------------
130                Underline off
142                Set uppercase/graphic mode
143                Flash off
145                Cursor up
146                Reverse mode off
147                Clear screen
148                Insert one character
157                Cursor left

Color codes
---------------------------------------------------------------------
  5                white
 28                red
 30                green
 31                blue
129                orange
144                black
149                brown
150                light red
151                light gray
152                medium gray
153                light green
154                light blue
155                dark gray
156                purple
158                yellow
159                cyan

Function keys
----------------------------------------------------------------
   3               Stop
  16               F9
  21               F10
  22               F11
  23               F12
  25               F13
  26               F14
 131               Run
 132               Help
 133               F1
 134               F3
 135               F5
 136               F7
 137               F2
 138               F4
 139               F6
 140               F8



3.4. KEKNEL


3.4.1. C64DX KERNEL ENTRY POINTS

[*** THE FOLLOWING VECTORS AND JUMP TABLES ARE NOT FINAL ***]

Where the default indirect vectors point to:

FF09   nirq             ;IRQ handler
FF0B   monitor_brk      ;BRK handler (Monitor)
FF0D   nnmi             ;NMI handler
FF0F   nopen            ;open
FF11   nclose           ;close
FF13   nchkin           ;chkin
FF15   nckout           ;ckout
FF17   nclrch           ;clrch
FF19   nbasin           ;basin
FF1B   nbsout           ;bsout
FF1D   nstop            ;stop key scan
FF1F   ngetin           ;getin
FF21   nclall           ;clall
FF23   monitor_parser   ;monitor command parser
FF25   nload            ;load
FF27   nsave            ;save

FF29   talk             ;Low level serial bus routines
FF2B   listen
FF2D   talksa
FF2F   second
FF31   acptr
FF33   ciout
FF35   untalk
FF37   unlisten

FF39   DOS_talk         ;newDOS routines
FF3B   DOS_listen
FF3D   DOS_talksa
FF3F   DOS_second
FF41   DOS_acptr
FF43   DOS_ciout
FF45   DOS_untalk
FF47   DOS_unlisten

FF49   Get_DOS
FF4B   Leave_DOS

FF4D   jmp spin_spout   ;setup fast serial port for input or output
FF50   jmp close_all    ;close all logical files for a given device
FF53   jmp c64mode      ;reconfigure system as a c/64 (no return!)
FF56   jmp monitor_call ;map in Monitor & call it
FF59   jmp bootsys      ;boot alternate system from disk
FF5C   jmp phoenix      ;call cold start routines, disk boot loader
FF5F   jmp lkupla       ;search tables for given la
FF62   jmp lkupsa       ;search tables for given sa
FF65   jmp swapper      ;swap to alternate display device
FF68   jmp pfkey        ;program function key
FF6B   jmp setbnk       ;set bank for load/save/verify/open
FF6E   jmp jsr_far      ;JSR to any bank, RTS to calling bank
FF71   jmp jmp_far      ;JMP to any bank
FF74   jmp lda_far      ;LDA (X),Y from bank Z
FF77   jmp sta_far      :STA (X),Y to   bank Z
FF7A   jmp cmp_far      ;CMP (X),Y to   bank Z
FF7D   jmp primm        ;print immediate (always JSR to this routine!)

FF80   <FF>             ;release number of C65 Kernel ($FF=not released)

FF81   jmp cint         ;init screen editor & display chips
FF84   jmp ioinit       ;init I/O devices (ports, timers, etc.)
FF87   jmp ramtas       ;initialize RAM for system
FF8A   jmp restor       ;restore vectors to initial system
FF8D   jmp vector       ;change vectors for user
FF90   jmp setmsg       ;control OS messages
FF93   jmp (isecond)    ;send sa after listen
FF96   jmp (italksa)    ;send sa after talk
FF99   jmp memtop       ;set/read top of memory
FF9C   jmp membot       ;set/read bottom of memory
FF9F   jmp key          ;scan keyboard
FFA2   jmp settmo       ;old IEEE set timeout value
FFA5   jmp (iacptr)     ;read a byte from active serial bus talker
FFA8   jmp (iciout)     ;send a byte to active serial bus listener
FFAB   jmp (iuntalk)    ;command serial bus device to stop talking
FFAE   jmp (iunlisten)  ;command serial bus device to stop listening
FFB1   jmp (ilisten)    ;command serial bus device to listen
FFB4   jmp (italk)      ;command serial bus device to talk
FFB7   jmp readss       ;return I/O status byte
FFBA   jmp setlfs       ;set la, fa, sa
FFBD   jmp setnam       ;set length and fn adr
FFC0   jmp (iopen)      ;open logical file
FFC3   jmp (iclose)     ;close logical file
FFC6   jmp (ichkin)     ;open channel in
FFC9   jmp (ickout)     ;open channel out
FFCC   jmp (iclrch)     ;close I/O channel
FFCF   jmp (ibasin)     ;input from channel
FFD2   jmp (ibsout)     ;output to channel
FFD5   jmp load         ;load from file
FFD8   jmp save         ;save to file
FFDB   jmp Set Time     ;set internal clock
FFDE   jmp Read Time    :read internal clock
FFE1   jmp (istop)      ;scan stop key
FFE4   jmp (igetin)     ;get char from queue
FFE7   jmp (iclall)     ;clear all logical files (see close all)
FFEA   jmp ScanStopKey  ;(was increment clock) & scan stop key
FFED   jmp scrorg       ;return current screen window size
FFF0   jmp plot         ;read/set x,y coord
FFF3   jmp iobase       ;return I/O base

FFF6   c65mode          ;C64/C65 interface
FFF8   c65mode

FFFA   nmi              ;processor hardware vectors
FFFC   reset
FFFE   irq_kernel


3.4.2. C64DX EDITOR JUMP TABLE

[*** THE FOLLOWING VECTORS AND JUMP TABLES ARE NOT FINAL ***]

E000   cint            ;initialize editor & screen
E003   disply          ;display character in .a, color in .x
E006   lp2             ;get a key from IRQ buffer into .a
E009   loopS           ;get a chr from screen line into .a
E00C   print           ;print character in .a
E00F   scrorg          ;get size of window (rows,cols) in .x, .y
E012   keyboard_scan   ;scan keyboard subroutine
E015   repeat          ;repeat key logic & CKIT2 to store decoded key
E018   plot            ;read or set (.c) cursor position in .x, .y
E01B   mouse_cmd       ;install/remove mouse driver
E01E   escape          ;execute escape function using chr in .a
E021   keyset          ;redefine a programmable function key
E024   editor_irq      ;IRQ entry
E027   palette_init    ;initialize VIC palette
E02A   swap            ;40/80 mode change
E02D   window          ;set top left or bottom right (.c) of window
E030   cursor          ;turn on or off (.c) soft cursor


3.4.3. C64DX BASIC JUMP TABLE

[*** THE FOLLOWING VECTORS AND JUMP TABLES ARE NOT FINAL ***]

   Format Conversions

7F00       ayint        ;convert floating point to integer
7F03       givayf       ;convert integer to floating point.
7F06       fout         ;convert floating point to ASCII string
7F09       val_1        ;convert ASCII string to floating point
7F0C       getadr       ;convert floating point to an address
7F0F       floatc       ;convert address to floating point

   Math Functions

7F12       fsub         ;MEM - FACC
7F15       fsubt        ;ARG - FACC
7F18       fadd         ;MEM + FACC
7F1B       faddt        ;ARG - FACC
7F1E       fmult        ;MEM * FACC
7F21       fmultt       ;ARG * FACC
7F24       fdiv         ;MEM / FACC
7F27       fdivt        ;ARG / FACC
7F2A       log          ;compute natural log of FACC
7F2D       int          ;perform BASIC INT() on FACC
7F30       sqr          ;compute square root of FACC
7F33       negop        ;negate FACC
7F36       fpwr         ;raise ARG to the MEM power
7F39       fpwrt        ;raise ARG to the FACC power
7F3C       exp          ;compute EXP of FACC
7F3F       cos          ;compute COS of FACC
7F42       sin          ;compute SIN of FACC
7F45       tan          ;compute TAN of FACC
7F48       atn          ;compute ATN of FACC
7F4B       round        ;round FACC
7F4E       abs          ;absolute value of FACC
7F51       sign         ;test sign of FACC
7F54       fcomp        ;compare FACC with MEM
7F57       rnd_0        ;generate random floating point number

   Movement

7F5A       conupk       ;move RAM MEM to ARG
7F5D       romupk       ;move ROM MEM to ARG
7F60       movfrm       :move RAM MEM to FACC
7F63       movfm        :move ROM MEM to FACC
7F66       movmf        :move FACC to MEM
7F69       movfa        ;move ARG to FACC
7F6C       movaf        ;move FACC to ARG
7F6F       run
7F72       runc
7F75       clear
7F78       new
7F7B       link_program
7F7E       crunch
7F81       FindLine
7F84       newstt
7F87       eval
7F8A       frmevl
7F8D       run_a_program
7F90       setexc
7F93       linget
7F96       garba2
7F99       execute_a_line
7F9C       chrget
7F9F       chrgot
7FA2       chkcom
7FAS       frmnum
7FA8       getadr
7FAB       getnum
7FAE       getbyt
7FB1       plsv

   Graphic Jump Table

8000       init         ;Graphics BASIC init (same as command=0)
8002       parse        ;Graphics BASIC command parser
8003       start        ;0      commands
8006       screendef    ;1
8008       screenopen   ;2
800A       screenclose  ;3
800C       screenclear  ;4
800E       screen       ;5
8010       setpen       ;6
8012       setpalette   ;7
8014       setdmode     ;8
8016       setdpat      ;9
8018       line         ;10
801A       box          ;11
801C       circle       ;12
801E       polygon      ;13
8020       ellipse      ;14
8022       viewpclr     ;15
8024       copy         ;16
8026       cut          ;17
8028       paste        ;18
802A       load         ;19
802C       char         ;20
802E       viewportdef  ;21


3.4.4. C64DX SOFT VECTORS

[*** THE FOLLOWING VECTORS AND JUMP TABLES ARE NOT FINAL ***]

   BASIC indirect vectors

02F7   jmp USR          ;USR vector (must be set by application)

02FC   esc_fn_vec       ;Escape Function vector
02FE   graphic_vector   ;Graphic Kernel vector
0300   ierror           ;indirect error (output error in .x)
0302   imain            ;indirect main (system direct loop)
0304   icrnch           ;indirect crunch (tokenization routine)
0306   iqplop           ;indirect list (char list)
0308   igone            ;indirect gone (char dispatch)
030A   ieval            ;indirect eval (symbol evaluation)
030C   iesclk           ;escape token crunch
030E   iescpr           ;escape token list
0310   iescex           ;escape token execute

   Kernel indirect vectors

02FA   iAutoScroll      ;AutoScroll used by BASIC, Monitor, Editor
0312   itime            ;(unused)
0314   iirq             ;IRQ
0316   ibrk             ;BRK
0318   inmi             ;NMI
031A   iopen
031C   iclose
031E   ichkin
0320   ickout
0322   iclrch
0324   ibasin
0326   ibsout
0328   istop
032A   igetin
032C   iclall
032E   exmon            ;Monitor command indirect
0330   iload
0332   isave

   Editor indirect vectors to routines & tables

0334   ctlvec           ;'contrl' characters
0336   shfvec           ;'shiftd' characters
0338   escvec           ;'escape' characters
033A   keyvec           ;post keyscan, pre-evaluation of keys
033C   keychk           ;post-evaluation, pre-buffering of keys
033E   decode           ;vectors to 6 keyboard matrix decode tables
   33E                   - Mode 1 --> normal keys
   340                   - Mode 2 --> <SHIFT> keys
   342                   - Mode 3 --> <C=> keys
   344                   - Mode 4 --> <CONTROL> keys
   346                   - Mode 5 --> <CAPS LOCK> keys
   348                   - Mode 6 --> <ALT> keys


3.4.5. KERNEL DOCUMENTATION

The  KERNEL is the ROM resident operating system of the Commodore 64DX
computer.  All input,  output,  and memory management is controlled by
the KERNEL. The KERNEL JUMP TABLE provides a standardized interface to
many   useful   routines  within  the  operating  system.  Application
programmers  are  encouraged  to  utilize  the JUMP TABLEs to simplify
their operations and guarantee their functionality should hardware or,
software modifications to the system become necessary.

C64 STANDARD KERNEL CALLS

The  following  system  calls  comprise the set of standard C64 system
calls for the C64 class of machines, including the PLUS-4.  Several of
the  calls,  however  function  somewhat  differently  or  may require
slightly  different setups. This was necessary to accommodate specific
features of the system,  notably the 40/80 column windowing Editor and
banked  memory  facilities.  As  with  all  Kernel  calls,  the system
configuration (BANK $FF) must be in context at the time of the call.


C64DX KERNEL JUMP TABLE DESCRIPTIONS


1. $FF81 CINT  ; initialize screen editor

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used
                           .Y used

               Memory:     init Editor RAM
                           init Editor I/O

               Flags:      none

         Example:

               SEI
               JSR $FF81   ; initialize screen editor
               CLI

CINT  is the Editor's initialization routine.  Editor indirect vectors
installed,  programmable key definitions assigned, and the ASC/DIN key
scanned for NATIONAL keyboard/charset determination. CINT sets the VIC
bank,  VIC nybble bank,  enables the character ROM, resets SID volume,
and clears the screen.  The only thing it does not do that pertains to
the Editor which is needed for IRQs  (keyscan, VIC cursor blink, split
screen modes), key lines, screen background colors, etc. (see IOINIT).
Because  CINT updates Editor indirect vectors that are used during IRQ
processing, you should disable IRQs prior to calling it. CINT utilizes
the status byte INIT STATUS as follows:

         $1104 bit 6 = 0  -->  Full initialization.
                               (Set INIT_STATUS bit 6)

                     = 1  -->  Partial initialization.
                               (not keymatrix pointers)
                               (not program key definitions)


2. $FF84 IOINIT  ; init I/O devices

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used
                           .Y used

               Memory:     initialize I/O

               Flags:      none

         Example:

               SEI
               JSR $FF84   ; initialize system I/O
               CLI

IOINIT  is  perhaps  the  major  function  of  the  Reset  handler. It
initializes  both CIA's (timers, keyboard serial port, user port), the
4510  port, the VIC chip, the UART and the DOS. It distinguishes a PAL
system from an NTSC one and sets PALCNT if PAL. The system IRQ source,
the VIC raster, is started (pending IRQs are cleared). IOINIT utilizes
the status byte INIT STATUS as follows:

         $1104 bit 7 = 0  -->  Full initialization.
                               (set INIT STATUS bit 7)

                     = 1  -->  Partial initialization.

You  should  be  sure IRQs are disabled before calling IOINIT to avoid
interrupts while the various I/O devices are being initialized.


3. $FF87 RAMTAS  ; init RAM and buffers

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used
                           .Y used

               Memory:     initializes RAM

               Flags:      none

         Example:

               JSR $FF87   ; initialize system RAM

RAMTAS  clears  all  base page RAM, allocates the sets pointers to the
top  and  bottom  of  system RAM and points the SYSTEM_VECTOR to BASIC
cold  start.  Lastly  it  sets  a  flag,  DEJAVU, to indicate to other
routines   that   system   RAM  has  been  initialized  and  that  the
SYSTEM_VECTOR  is  valid.  It  should  be  noted that the C64DX RAMTAS
routine does NOT in any way test RAM.


4. $FF8A RESTOR  ; init Kernel indirects

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used
                           .Y used

               Memory:     kernel indirects restored

               Flags:      none

         Example:

               SEI
               JSR $FF8A   ; restore kernel indirects
               CLI

RESTOR  restores the default values of all the Kernel indirect vectors
from the Kernel ROM list.  It does NOT affect any other vectors,  such
as  those  used  by  the  Editor  (see CINT) and BASIC.  Because it is
possible for an interrupt (IRQ or NMI) to occur during the updating of
the interrupt indirect vectors, you should disable interrupts prior to
calling RESTOR. See also the VECTOR call.


5. $FF8D VECTOR  ; init or copy indirects

         Preparation:

               Registers:  .X = adr (low) of user list
                           .Y = adr (high) of user list

               Memory:     system map

               Flags:      .C = 0 --> load Kernel vectors
                           .C = 1 --> copy Kernel vectors

               Calls:      none

         Results:

               Registers:  .A used
                           .Y used

               Memory:     as per call

               Flags:      none

         Example:

               LDX #save_lo
               LDY #save_hi
               SEC
               JSR $FF87  ; copy indirects to 'save'

VECTOR reads or writes the Kernel RAM indirect vectors. Calling VECTOR
with  the carry status set stores the current contents of the indirect
vectors  to  the RAM address passed in the .X and .Y registers (to the
current RAM bank).  Calling VECTOR with the carry status clear updates
the Kernel indirect vectors from the user list passed in the .X and .Y
registers (from the current RAM bank). Interrupts (IRQ and NMI) should
be disabled when updating the indirects. See also the RESTOR call.


6. $FF90 SETMSG  ; kernel messages on/off

         Preparation:

               Registers:  .A = message control

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     MSGFLG updated

               Flags:      none

         Example:

               LDA #0
               JSR $FF90   ; turn OFF all Kernel messages

SETMSG  updates  the  Kernel message flag byte MSGFLG which determines
whether system error and/or control messages will be displayed.  BASIC
normally  disables error messages always and disables control messages
in 'run' mode. Note that the Kernel error messages are not the verbose
ones  printed by BASIC,  but simply the 'I/O ERROR #' message that you
see  when  in  the  Monitor,  for example.  Examples of Kernel control
messages are 'LOADING' and 'FOUND'. The MSGFLG control bits are:

         MSGFLG bit 7 = 1 --> enable CONTROL messages
                bit 6 = 1 --> enable ERROR messages


7. $FF93 SECND  ; serial: send SA after LISTN

         Preparation:

               Registers:  .A = SA (secondary address)

               Memory:     system map

               Flags:      none

               Calls:      LISTN

         Results:

               Registers:  .A used

               Memory:     STATUS ($90)

               Flags:      none

         Example:

               LDA #8
               JSR $FFB1   ; LISTN device 8
               LDA #15
               JSR $FF93   ; pass it SA #15

SECND  is  a low-level serial routine used to send a secondary address
(SA) to a LISTeNing device  (see LISTN Kernel call).  An SA is usually
used  to  provide setup information to a device before the actual data
I/O  operation  begins.  Attention  is released after a call to SECND.
SECND is not used to send an SA to a TALKing device (see TKSA).  (Most
applications  should  use  the higher level I/O routines: see OPEN and
CKOUT).


8. $FF96 TKSA  ; serial: send SA after TALK

         Preparation:

               Registers:  .A = SA (secondary address)

               Memory:     system map

               Flags:      none

               Calls:      TALK

         Results:

               Registers:  .A used

               Memory:     STATUS ($90)

               Flags:      none

         Example:

               LDA #8
               JSR $FFB4   ; TALK device 8
               LDA #15
               JSR $FF93   ; pass it SA #15

TKSA  is  a  low-level serial routine used to send a secondary address
(SA)  to a device commanded to TALK  (see TALK Kernel call).  An SA is
usually  used  to  provide  setup  information  to a device before the
actual  data  I/O operation begins.  (Most applications should use the
higher level I/O routines: see OPEN and CHKIN).


9. $FF99 MEMTOP  ; set/read top of system RAM

         Preparation:

               Registers:  .X = lsb of MEMSIZ
                           .Y = msb of MEMSIZ

               Memory:     system map

               Flags:      .C = 0 --> set top of memory
                           .C = 1 --> read top of memory

               Calls:      none

         Results:

               Registers:  .X = lsb of MEMSIZ
                           .Y = msb of MEMSIZ

               Memory:     MEMSIZ

               Flags:      none

         Example:

               SEC
               JSR $FF99   ; get top of user RAM
               DEY
               CLC
               JSR $FF99   ; lower it 1 block

MEMTOP  is  used  to read or set the top of system RAM,  pointed to by
MEMSIZ.  This  call  is  included  in the C64DX for completeness,  but
neither  the  Kernel nor BASIC utilize MEMTOP as it has little meaning
in  the  banked  memory  environment  of the computer (even the RS-232
buffers  are  permanently  allocated).  None-the-less,  set  the carry
status  to  load  MEMSIZ  into .X  and .Y,  and clear it to update the
pointer  from .X and .Y.  Note that MEMSIZ references only system RAM.
The Kernel initially sets MEMSIZ to $FF00.


10. $FF9C MEMBOT  ; set/read bottom of system RAM

         Preparation:

               Registers:  .X = lsb of MEMSTR
                           .Y = msb of MEMSTR

               Memory:     system map

               Flags:      .C = 0 --> set bot of memory
                           .C = 1 --> read bot of memory

               Calls:      none

         Results:

               Registers:  .X = lsb of MEMSTR
                           .Y = msb of MEMSTR

               Memory:     MEMSTR

               Flags:      none

         Example:

               SEC
               JSR $FF9C   ; get bottom of user RAM_0
               INY
               CLC
               JSR $FF9C   ; raise it 1 block

MEMBOT  is used to read or set the bottom of system RAM, pointed to by
MEMSTR.  This  call  is  included  in the C64DX for completeness,  but
neither  the  Kernel nor BASIC utilize MEMBOT as it has little meaning
in the banked memory environment of the C64DX. None-the-less,  set the
carry status to load MEMSTR into .X and .Y, and clear it to update the
pointer  from .X and .Y.  Note that MEMSTR references only system RAM.
The Kernel initially sets MEMSTR to $2000 (BASIC text starts here).


11. $FF9F KEY  ; scan keyboard

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     keyboard buffer
                           keyboard flags

               Flags:      none

         Example:

               JSR $FF9F   ; scan the keyboard

KEY  is  an  Editor  routine  which  scans  the  entire  keyboard.  It
distinguishes  between shifted and unshifted keys,  control keys,  and
programmable  keys,  setting  keyboard  status  bytes and managing the
keyboard buffer. After decoding the key, KEY will manage such features
as toggling cases,  pauses or delays, and key repeats.  It is normally
called  by  the operating system during the 60Hz IRQ processing.  Upon
conclusion,  KEY  leaves the keyboard hardware driving the key-line on
which the STOP key is located.

There  are two indirect RAM jumps encountered during a keyscan: KEYVEC
($33A)  and  KEYCHK ($33C).  KEYVEC (alias KEYLOG) is taken whenever a
key depression is discovered,  before the key in  .A has been decoded.
KEYCHK is taken after the key has been decoded, just before putting it
into  the  key  buffer.  KEYCHK carries the ASCII character in .A, the
keycode in .Y, and the shift-key status in .X.

The keyboard decode matrices are addressed via indirect RAM vectors as
well, located at DECODE.


12. $FFA2 SETTMO  ; (reserved)

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     TIMOUT

               Flags:      none

         Example:

               LDA #value
               JSR $FFA2   ; update TIMOUT byte

SETTMO  is  unused  in the C64DX and is included for compatibility and
completeness.  It  is  used  in  the  C64  by  the  IEEE communication
cartridge to disable I/O timeouts.


13. $FFA5 ACPTR  ; serial: byte input.

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      TALK
                           TKSA (if necessary)

         Results:

               Registers:  .A = data byte

               Memory:     STATUS ($90)

               Flags:      none

         Example:

               JSR $FFA5   ; input a byte from serial bus
               STA data

ACPTR  is  a low-level serial I/O utility to accept a single byte from
the  current serial bus TALKer using full handshaking.  To prepare for
this  routine  a  device  must first have been established as a TALKer
(see TALK) and passed a secondary address if necessary (see TKSA). The
byte is returned in .A. (Most applications should use the higher level
I/O routines: see BASIN and GETIN).


14. $FFA8 CIOUT  ; serial: byte output

         Preparation:

               Registers:  .A = data byte

               Memory:     system map

               Flags:      none

               Calls:      LISTN
                           SECND (if necessary)

         Results:

               Registers:  .A used

               Memory:     STATUS ($90)

               Flags:      none

         Example:

               LDA data
               JSR $FFA8   ; send a byte via serial bus

CIOUT  is  a low-level serial I/O utility to transmit a single byte to
the current serial bus LISTNer using full handshaking.  To prepare for
this  routine  a  device must first have been established as a LISTNer
(see LISTN)  and passed a secondary address if necessary  (see SECND).
The  byte  is  passed  in  .A.  Serial  output data is buffered by one
character,  with the last character being transmitted with EOI after a
call  to  UNLSN.  (Most  applications  should use the higher level I/O
routines; see BSOUT).


15. $FFAB UNTLK  ; serial: send untalk

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used

               Memory:     STATUS ($90)

               Flags:      none


         Example:

               JSR $FFAB   ; UNTALK serial device

UNTLK  is  a  low-level Kernel serial bus routine that sends an UNTALK
command to all serial bus devices.  It commands all TALKing devices to
stop sending data.  (Most applications should use the higher level I/O
routines; see CLRCH).


16. $FFAE UNLSN  ; serial: send unlisten

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used

               Memory:     STATUS ($90)

               Flags:      none

         Example:

               JSR $FFAE   ; UNLISTEN serial device

UNLSN  is a low-level Kernel serial bus routine that sends an UNLISTEN
command  to all serial bus devices.  It commands all LISTENing devices
to  stop reading data.  (Most applications should use the higher level
I/O routines; see CLRCH).


17. $FFB1 LISTN  ; serial: send listen command

         Preparation:

               Registers:  .A = device (0-31)

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used

               Memory:     STATUS ($90)

               Flags:      none

         Example:

               JSR $FFB1   ; command device to LISTEN

LISTN  is  a  low-level Kernel serial bus routine that sends an LISTEN
command  to  the  serial  bus device in .A.  It commands the device to
start reading data. (Most applications should use the higher level I/O
routines; see CKOUT).


18. $FFB4 TALK  ; serial: send talk command

         Preparation:

               Registers:  .A = device (0-31)

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used

               Memory:     STATUS ($90)

               Flags:      none

         Example:

               JSR $FFB4   ; command device to TALK

TALK  is  a  low-level  Kernel  serial  bus routine that sends an TALK
command  to  the  serial  bus device in .A.  It commands the device to
start sending data. (Most applications should use the higher level I/O
routines; see CHKIN).


19. $FFB7 READSS  ; read I/O status byte

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A = STATUS ($90 or $A6)

               Memory:     STATUS cleared if RS-232 ($A6)

               Flags:      none

         Example:

               JSR $FFB7   ; STATUS for last I/O

READSS (alias READST) returns the status byte associated with the last
I/O  operation  (serial  or RS-232)  performed.  Serial bus and newDOS
devices update STATUS ($90) and RS-232 I/O updates RSSTAT ($A6).  Note
that,  to  simulate  an  6551,  RSSTAT is cleared after it is read via
READSS.  The  last  I/O  operation is determined by the contents of FA
($BA), thus applications which drive I/O devices using the lower-level
Kernel calls should not use READSS.


20. $FFBA SETLFS  ; set channel LA, FA, SA

         Preparation:

               Registers:  .A = LA (logical #)
                           .X = FA (device #)
                           .Y = SA (secondary adr)

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     LA, FA, SA updated

         Example:

               see OPEN

SETLFS  sets  the  logical  file number (LA, $B8),  device number (FA,
$BA),  and secondary address (SA, $B9) for the higher-level Kernel I/O
routines.  The  LA  must  be  unique among OPENed files and is used to
identify specific files for I/O operations. The device number range is
0  to 31 and is used to target I/O.  The SA is a command to be sent to
the indicated device, usually to place it in a particular mode. If the
SA  is  not needed,  the .Y register should pass $FF.  SETLFS is often
used along with SETNAM and SETBNK calls prior to OPENs. See the Kernel
OPEN, LOAD, and SAVE calls for examples.


21. $FFBD SETNAM  ; set filename pointers

         Preparation:

               Registers:  .A = string length
                           .X = string adr_low
                           .Y = string adr_high

               Memory:     system map

               Flags:      none

               Calls:      SETBNK

         Results:

               Registers:  none

               Memory:     FNLEN, FNADR updated

               Flags:      none

         Example:

               see OPEN

SETNAM  sets up the filename or command string for higher-level Kernel
I/O  calls  such as  OPEN,  LOAD,  and  SAVE.  The string (filename or
command)  length is passed in .A and updates FNLEN ($B7).  The address
of  the  string is passed in .X (low) and Y (high).  See the companion
call,  SETBNK  which specifies which RAM bank the string is found.  If
there  is  no  string,  SETNAM should still be called and a null ($00)
length specified  (the address does not matter).  SETNAM is often used
along  with  SETBNK  and  SETLFS calls prior to OPENs.  See the Kernel
OPEN, LOAD, and SAVE calls for examples.


22. $FFC0 OPEN  ; open logical file

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      SETLFS, SETNAM, SETBNK

         Results:

               Registers:  .A = error code (if any)
                           .X used
                           .Y used

               Memory:     setup for I/O
                           STATUS, RSSTAT updated

               Flags:      .C = 1 --> error

         Example:          OPEN 1,8,15,"I0"

               LDA #length    ; fnlen
               LDX #<filename ; fnadr (command)
               LDY #>filename
               JSR $FFBD      ; SETNAM

               LDX #0         ; fnbank (RAM_0)
               JSR $FF68      ; SETBNK

               LDA #1         ; la
               LDX #8         ; fa
               LDY #15        ; sa
               JSR $FFBA      ; SETLFS

               JSR $FFC0      ; OPEN

               BCS error

      filename .BYTE 'I0'
      length   = 2

OPEN  prepares  a logical file for I/O operations. It creates a unique
entry  in the Kernel logical file tables LAT ($362),  FAT ($36C),  and
SAT ($376)  using its index LDTND ($98)  and data supplied by the user
via   SETLFS.   There   can   be   up  to  ten  logical  files  OPENed
simultaneously.  OPEN  performs  device  specific  opening  tasks  for
serial,  RS-232,  keyboard & screen,  devices,  including clearing the
previous  status and transmitting any given filename or command string
supplied  by  the  user via SETNAM and SETBNK.  The I/O status will be
updated appropriately and can be read via READSS.

The  path  to  OPEN  is  through  an  indirect  RAM  vector  at  $31A.
Applications  may  therefore  provide  their  own  OPEN  procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


23. $FFC3 CLOSE  ; close logical file

         Preparation:

               Registers:  .A = LA (logical #)

               Memory:     system map

               Flags:      .C (see text below)

               Calls:      none

         Results:

               Registers:  .A = error code (if any)
                           .X used
                           .Y used

               Memory:     logical tables updated
                           STATUS, RSSTAT updated

               Flags:      .C = 1 --> error

         Example:

               LDA #1      ; la
               JSR $FFC3   ; CLOSE
               BCS error

CLOSE removes the logical file (LA) passed in .A from the logical file
tables  and  performs device specific closing tasks. Keyboard, screen,
and  any  unOPENed  files  pass through. RS-232 devices are not closed
until  all buffered data has been transmitted. Serial files are closed
by  transmitting  a  'close'  command  (if an SA was given when it was
opened), sending any, buffered character, and UNLiSTeNing the bus.

There  is  a  special provision incorporated into the CLOSE routine of
systems  featuring BASIC DOS command.  If the following conditions are
all  TRUE,  a full CLOSE is NOT performed:  the table entry is removed
but  a  'close' command is NOT transmitted to the device.  This allows
the  disk command channel to be properly OPENed and CLOSEd without the
disk operating system closing ALL files on its end:

         .C = 1 --> indicates special CLOSE
         FA >=8 --> device is a disk
         SA =15 --> command channel

The  path  to  CLOSE  is  through  an  indirect  RAM  vector  at $31C.
Applications  may  therefore  provide  their  own  CLOSE procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


24. $FFC6 CHKIN  ; set input channel

         Preparation:

               Registers:  .X = LA (logical #)

               Memory:     system map

               Flags:      none

               Calls:      OPEN

         Results:

               Registers:  .A = error code (if any)
                           .X used
                           .Y used

               Memory:     LA, FA, SA, DFLTN
                           STATUS, RSSTAT updated

               Flags:      .C = 1 --> error

         Example:

               LDX #1      ; la
               JSR $FFC6   ; CHKIN
               BCS error

CHKIN  establishes  an input channel to the device associated with the
logical address (LA) passed in  .X, in preparation for a call to BASIN
or  GETIN.  The Kernel variable DFLTN ($99) is updated to indicate the
current input device and the variables LA, FA, and SA are updated with
the  file's  parameters from its entry in the logical file tables (put
there  by OPEN).  CHKIN performs certain device specific tasks: screen
and  keyboard  channels  pass  through, and serial channels are sent a
TALK  command  and  the  SA transmitted (if necessary).  Call CLRCH to
restore normal I/O channels.

CHKIN is required for all input except the keyboard. If keyboard input
is desired and no other input channel is established,  you do not need
to  call  CHKIN or OPEN.  The keyboard is the default input device for
BASIN and GETIN.

The  path  to  CHKIN  is  through  an  indirect  RAM  vector  at $31E.
Applications  may  therefore  provide  their  own  CHKIN procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


25. $FFC9 CKOUT  ; set output channel

         Preparation:

               Registers:  .X = LA (logical #)

               Memory:     system map

               Flags:      none

               Calls:      OPEN

         Results:

               Registers:  .A = error code (if any)
                           .X used
                           .Y used

               Memory:     LA, FA, SA, DFLTO
                           STATUS, RSSTAT updated

               Flags:      .C = 1 --> error

         Example:

               LDX #1      ; la
               JSR $FFC9   ; CKOUT
               BCS error

CKOUT  establishes an output channel to the device associated with the
logical address (LA) passed in .X, in preparation for a call to BSOUT.
The  Kernel  variable  DFLTO  ($9A) is updated to indicate the current
output device and the variables  LA,  FA,  and SA are updated with the
file's parameters from its entry in the logical file tables (put there
by  OPEN).  CKOUT performs  certain  device  specific tasks:  keyboard
channels  are  illegal,  screen  channels  pass  through,  and  serial
channels  are  sent  a  LISTN  command  and  the  SA  transmitted  (if
necessary). Call CLRCH to restore normal I/O channels.

CKOUT  is  required for all output except the screen. If screen output
is desired and no other output channel is established, you do not need
to  call  CKOUT  or OPEN.  The screen is the default output device for
BSOUT.

The  path  to  CKOUT  is  through  an  indirect  RAM  vector  at $320.
Applications  may  therefore  provide  their  own  CKOUT procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


26. $FFCC CLRCH  ; restore default channels

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used

               Memory:     DFLTI, DFLTO updated

               Flags:      none

         Example:

               JSR $FFCC   ; restore default I/O

CLRCH  (alias  CLRCHN)  is used to clear all open channels and restore
the  system  default  I/O  channels  after  other  channels  have been
established via CHKIN and/or CHKOUT. The keyboard is the default input
device  and  the  screen  is  the default output device.  If the input
channel  was to a serial device,  CLRCH first UNTLKs it. If the output
channel was to a serial device, it is UNLiSteNed first.

The  path  to  CLRCH  is  through  an  indirect  RAM  vector  at $322.
Applications  may  therefore  provide  their  own  CLRCH procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


27. $FFCF BASIN  ; input from channel

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      CHKIN (if necessary)

         Results:

               Registers:  .A = character (or error code)

               Memory:     STATUS, RSSTAT updated

               Flags:      .C = 1 if error

         Example:

               LDY #0      ; index
          more JSR $FFCF   ; input a character
               STA data,Y  ; buffer it
               INY
               CMP #$0D    ; carriage return?
               BNE more

BASIN  (alias  CHRIN)  reads a character from the current input device
(DFLTN, $99)  and returns it in .A.  Input from devices other than the
keyboard  (the default input device)  must be OPENed and CHKINed.  The
character  is  read  from the input buffer associated with the current
input channel:

1. RS-232 data is returned a character at a time from the RS-232 input
   buffer,  waiting  until  a  character is received if necessary.  If
   RSSTAT  is  bad  from a prior operation,  input is skipped and null
   input (carriage return) is substituted.

2. Serial  data  is  returned  a character at a time directly from the
   serial  bus,  waiting  until  a character is sent if necessary.  If
   STATUS ($90)  is  bad from a prior operation,  input is skipped and
   null input (carriage return) is substituted.

3. Screen  data is read from screen RAM starting at the current cursor
   position  and ending with a faked carriage return at the end of the
   logical screen line.

4. Keyboard  data is input by turning on the cursor reading characters
   from  the  keyboard  buffer  and echoing them on the screen until a
   carriage return is encountered. Characters are then returned one at
   a time from the screen until all characters input have been passed,
   including  the carriage return.  Any calls after the eol will start
   the process over again.

The  path  to  BASIN  is  through  an  indirect  RAM  vector  at $324.
Applications  may  therefore  provide  their  own  BASIN procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


28. $FFD2 BSOUT  ; output to channel

         Preparation:

               Registers:  .A = character

               Memory:     system map

               Flags:      none

               Calls:      CKOUT (if necessary)

         Results:

               Registers:  .A = error code (if any)

               Memory:     STATUS, RSSTAT updated

               Flags:      .C = 1 if error

         Example:

               LDA #character
               JSR $FFD2   ; output a character

BSOUT  (alias CHROUT) writes the character in .A to the current output
device  (DFLTO,  $9A).  Output  to  devices other than the screen (the
default  output device)  must be OPENed and CKOUTed.  The character is
written  to  the  output  buffer  associated  with  the current output
channel:

1. RS-232  data  is  put  a character at a time into the RS-232 output
   buffer, waiting until there is room if necessary.

2. Serial  data  is  passed  to  CIOUT which buffers one character and
   sends the previous character.

3. Screen data is put into screen RAM at the current cursor position.

4. Keyboard output is illegal.

The  path  to  BSOUT  is  through  an  indirect  RAM  vector  at $326.
Applications  may  therefore  provide  their  own  BSOUT procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


29. $FFD5 LOAD  ; load from file

         Preparation:

               Registers:  .A = 0 --> LOAD
                           .A > 0 --> VERIFY
                           .X = load adr_lo (if SA=0)
                           .Y = load adr_hi (if SA=0)

               Memory:     system map

               Flags:      none

               Calls:      SETLFS, SETNAM, SETBNK

         Results:

               Registers:  .A = error code (if any)
                           .X = ending adr_lo
                           .Y = ending adr_hi

               Memory:     per command
                           STATUS updated

               Flags:      .C = 1 --> error

         Example:          LOAD "program",8,1

               LDA #length    ; fnlen
               LDX #<filename ; fnadr
               LDY #>filename
               JSR $FFBD      ; SETNAM

               LDA #0         ; load/verify bank (RAM_0)
               LDX #0         ; fnbank (RAM_0)
               JSR $FF68      ; SETBNK

               LDA #0         ; la (not used)
               LDX #8         ; fa
               LDY #$FF       ; sa (SA>0 normal load)
               JSR $FFBA      ; SETLFS

               LDA #0         ; load, not verify
               LDX #<load_adr ; (used only if SA=0)
               LDY #>load_adr ; (used only if SA=0)
               JSR $FFD5      ; LOAD
               BCS error
               STX end_lo
               STY end_hi

      filename .BYTE 'program'
      length   = 7

This  routine LOADs data from an input device into memory. It can also
be  used  to  VERIFY that data in memory matches that in a file.  LOAD
performs device specific tasks for serial LOADs.  You cannot LOAD from
RS-232 devices,  the screen, or the keyboard.  While LOAD performs all
the  tasks of an OPEN, it does NOT create any logical files as an OPEN
does. Also note that LOAD cannot 'wrap' memory banks. As with any I/O,
the  I/O  status  is updated appropriately and can be read via READSS.
LOAD has two options that the user must select:

1. LOAD  vs.  VERIFY:  the  contents  of .A passed at the call to LOAD
   determines which mode is in effect. If .A is zero, a LOAD operation
   will  be  performed  and  memory  will  be  overwritten.  If  .A is
   non-zero,  a  VERIFY  operation  will  be  performed and the result
   passed via the error mechanism.

2. LOAD  ADDRESS:  the  secondary  address  (SA)  setup by the call to
   SETLFS determines  where  the LOAD starting address comes from.  If
   the SA is zero, the user wants the address in .X and .Y at the time
   of  the call to be used.  If the SA is non-zero,  the LOAD starting
   address  is read from the file header itself and the file loaded to
   the same place from which it was SAVEd.

The  serial  LOAD  routine  automatically  attempts to access a newDOS
drive,  then  attempts to BURST load a file, and resorts to the normal
load mechanism (but still using the FAST serial routines) if the BURST
handshake is not returned.

The  path  to  LOAD  is  through  an  indirect  RAM  vector  at  $330.
Applications  may  therefore  provide  their  own  LOAD  procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


30. $FFD8 SAVE  ; save to file

         Preparation:

               Registers:  .A = pointer to start adr
                           .X = end_adr_lo
                           .Y = end_adr_hi

               Memory:     system map

               Flags:      none

               Calls:      SETLFS, SETNAM, SETBNK

         Results:

               Registers:  .A = error code (if any)
                           .X = used
                           .Y = used

               Memory:     STATUS updated

               Flags:      .C = 1 --> error

         Example:          SAVE "program",8

               LDA #length     ; fnlen
               LDX #<filename  ; fnadr
               LDY #>filename
               JSR $FFBD       ; SETNAM

               LDA #0          ; save from bank (RAM_0)
               LDX #0          ; fnbank (RAM_0)
               JSR $FF68       ; SETBNK

               LDA #0          ; la (not used)
               LDX #8          ; fa
               LDY #0          ; sa (cassette only)
               JSR $FFBA       ; SETLFS

               LDA #start      ; pointer to start address
               LDX end         ; ending address lo
               LDY end+1       ; ending address hi
               JSR $FFD8       ; SAVE
               BCS error

      filename .BYTE 'program'
      length   = 7
      start    .WORD address1  ; page_0
      end      .WORD address2

This routine SAVEs data from memory to an output device. SAVE performs
device  specific  tasks  for serial SAVEs. You cannot SAVE from RS-232
devices,  the  screen,  or  the keyboard.  While SAVE performs all the
tasks  of  an  OPEN,  it  does NOT create any logical files as an OPEN
does. The starting address of the area to be SAVEd must be placed in a
base-page  vector  and the address of this vector passed to SAVE in .A
at the time of the call. The address of the last byte to be SAVEd PLUS
ONE is passed in .X and .Y at the same time.

SAVE  first attempts to access a newDOS drive. There is no BURST save:
the  normal  FAST  serial  routines are used. As with any I/O, the I/O
status will be updated appropriately and can be read via READSS.

The  path  to  SAVE  is  through  an  indirect  RAM  vector  at  $332.
Applications  may  therefore  provide  their  own  SAVE  procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


31. $FFDB SETTIM  ; set internal clock

         Preparation:

               Registers:  .A = hours
                           .X = minutes
                           .Y = seconds
                           .Z = tenths

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     TOD at CIA $DC00 updated

               Flags:      none

         Example:

               LDA #0      ; reset clock
               TAX
               TAY
               TAZ
               JSR $FFDB   ; SETTIM

SETTIM sets the system CIA 24-hour TOD clock, which counts tenths of a
second and automatically wraps at the 24-hour point.


32. $FFDE RDTIM  ; read internal clock

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A = hours
                           .X = minutes
                           .Y = seconds
                           .Z = tenths

               Memory:     none

               Flags:      none

         Example:

               JSR $FFDE   ; RDTIM


RDTIM reads the system CIA 24-hour TOD clock, which counts tenths of a
second. The timer is automatically wrapped at the 24-hour point.


33. $FFE1 STOP  ; scan stop key

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A = last keyboard row
                           .X = used (if STOP key)

               Memory:     none

               Flags:      status valid

         Example:

               JSR $FFE1   ; scan STOP key
               BEQ stop    ; branch if down

STOP  checks a Kernel variable STKEY ($91),  which is updated by UDTIM
during  normal  IRQ  processing and contains the last scan of keyboard
column  C7.  The  STOP key is bit-7,  which will be zero if the key is
down.  If  it is,  default I/O channels are restored via CLRCH and the
keyboard queue is flushed by resetting NDX ($D0). The keys on keyboard
line C7 are:

             bit:     7    6    5    4    3    2    1    0
             key:    STOP  Q   C=  SPACE  2  CTRL  <--   1

The  path  to  STOP  is  through  an  indirect  RAM  vector  at  $328.
Applications  may  therefore  provide  their  own  STOP  procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


34. $FFE4 GETIN  ; read buffered data

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      CHKIN (if necessary)

         Results:

               Registers:  .A = character (or error code)
                           .X used
                           .Y used

               Memory:     STATUS, RSSTAT updated

               Flags:      .C = 1 if error

         Example:

          wait JSR $FFE4   ; get any key
               BEQ wait
               STA character

GETIN  reads  a  character  from  the current input device (DFLTN $99)
buffer  and  returns  it  in  .A.  Input  from  devices other than the
keyboard  (the  default input device) must be OPENed and CHKINed.  The
character  is  read  from the input buffer associated with the current
input channel:

1. Keyboard input: a character is removed from the keyboard buffer and
   passed in .A. If the buffer is empty, a null ($00) is returned.

2. RS-232  input:  a character is removed from the RS-232 input buffer
   and passed in .A.  If the buffer is empty, a null ($00) is returned
   (use READSS to check validity).

3. Serial input:  GETIN automatically jumps to BASIN. See BASIN serial
   I/O.

4. Screen input:  GETIN automatically jumps to BASIN. See BASIN serial
   I/O.

The  path  to  GETIN  is  through  an  indirect  RAM  vector  at $32A.
Applications  may  therefore  provide  their  own  GETIN procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


35. $FFE7 CLALL  ; close all files and channels

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used

               Memory:     LDTND, DFLTN, DFLTO updated

               Flags:      none

         Example:

               JSR $FFE7   ; close files

CLALL  deletes  all  logical file table entries by resetting the table
index,  LDTND  ($98).  It clears current serials channels (if any) and
restores the default I/O channels via CLRCH.

The  path  to  CLALL  is  through  an  indirect  RAM  vector  at $32C.
Applications  may  therefore  provide  their  own  CLALL procedures or
supplement  the  system's  by  re-directing  this  vector to their own
routine.


36. $FFEA ScanStopKey (was UDTIM, which has no purpose on C64DX)

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used

               Memory:     TIME, TIMER, STKEY updated

               Flags:      none

         Example:

               JSR $FFEA   ; ScanStopKey

Scans  key  line C7, on which the STOP key lies, and stores the result
in STKEY ($91). The Kernel routine STOP utilizes this variable.


37. $FFED SCRORG  ; get current screen window size

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A = screen width
                           .X = window width
                           .Y = window height

               Memory:     none

               Flags:      none

         Example:

               JSR $FFED   ; SCRORG

SCRORG returns active window's size (maximum row & column #) & origin.

entry: nothing required.

exit:  .C = max. screen width (0=80, 1=40)       default = 0
       .X = max. column number (# columns - 1)   default = 79
       .Y = max. line number (# lines minus 1)   default = 24

       .A = window address (home position), low  default = $0800
       .Z = window address, high


38. $FFF0 PLOT  ; read/set cursor position

         Preparation:

               Registers:  .X = cursor line
                           .Y = cursor column

               Memory:     system map

               Flags:      .C = 0 --> set cursor position
                           .C = 1 --> get cursor position

               Calls:      none

         Results:

               Registers:  .X = cursor line
                           .Y = cursor column

               Memory:     TBLX, PNTR updated

               Flags:      .C = 1 --> error

PLOT Reads or sets the cursor position within current window.

Entry: .C = 1  Returns  the  cursor   position   (.Y=column,  .X=line)
               relative  to  the  current  window  origin  (NOT screen
               origin).

       .C = 0  Sets   the   cursor   position   (.Y=column,   .X=line)
               relative  to  the  current  window  origin  (NOT screen
               origin).

Exit:  When  reading  position,  .X=line,  .Y=column,  .C=1 if wrapped
       line.

       When setting new position, .X=line, .Y=column, and

       .C = 0  Normal exit.  The cursor has been moved to the position
               contained  in  .X  &  .Y relative to window origin (see
               SCRORG).

       .C = 1  Error  exit.  The  requested  position  was outside the
               current  window  (see SCRORG).  The cursor has not been
               moved.

When called with the carry status set, PLOT returns the current cursor
position  relative  to the current window origin  (NOT screen origin).
When  called  with  the  carry status clear,  PLOT attempt to move the
cursor to the indicated line and column relative to the current window
origin  (NOT screen origin).  PLOT will return a clear carry status if
the cursor was moved, and a set carry status if the requested position
was outside the current window (NO CHANGE has been made).

Editor variables that are useful:

         SCBOT - $E4 --> window bottom
         SCTOP - $E5 --> window top
         SCLF  - $E6 --> window left side
         SCRT  - $E7 --> window right side

         TBLX  - $EC --> cursor line
         PNTR  - $ED --> cursor column

         LINES - $EE --> maximum screen height
         COLUMNS $EF --> maximum screen width


39. $FFF3 IOBASE  ; read base address of I/O block

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .X = lsb of I/O block
                           .Y = msb of I/O block

               Memory:     none

               Flags:      none

         Example:

               JSR $FFF3   ; find the I/O block

IOBASE  is  unused  in the C64DX and is included for compatibility and
completeness. It returns the address of the I/O block in .X and .Y.


NEW C64DX KERNEL CALLS

The  following  system  calls  comprise  a  set  of  extensions to the
standard  CBM  jump table. They are specifically for the C64DX machine
and  as  such  should  not be considered as permanent additions to the
standard  jump  table. With the exception of C64MODE they are all true
subroutines and will terminate via RTSs. As with all Kernel calls, the
system  configuration (BANK $FF) must be in context at the time of the
call.


1. $FF4D SPIN_SPOUT  ;setup fast serial ports for I/O

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      .C = 0  -->  select SPINP
                           .C = 1  -->  select SPOUT

               Calls:      none

         Results:

               Registers:  .A used

               Memory:     CIA_1, FSDIR register

               Flags:      none

         Example:

               CLC
               JSR $FF4D   ;setup for fast serial input

The  fast serial protocol utilizes CIA_1 (6526 at $DC00) and a special
driver  circuit  controlled  in  part by the FSDIR register. SPINP and
SPOUT  are  routines  used  by  the  system to set up the CIA and fast
serial  driver  circuit  for input or output. SPINP sets up CRA (CIA_1
register  14)  and  clears the FSDIR bit for input. SPOUT sets up CRA,
ICR (CIA_1 register 13), timer A (CIA_l registers 4 & 5), and sets the
FSDIR  bit  for  output.  Note  the  state of the TOD_IN bit of CRA is
always  preserved.  These  routines  are required only by applications
driving the fast serial bus themselves from the lowest level.


2. $FF50 CLOSE_ALL  ;close all files on a device

         Preparation:

               Registers:  .A --> device # (FA: 0-31)

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used
                           .Y used

               Memory:     none

               Flags:      none

         Example:

               LDA #$08
               JSR $FF50   ; close all files on device 8

The  FAT  is  searched  for  the  given  FA.  A  proper CLOSE is
performed  for all matches. If one of the CLOSEd channels is the
current I/O channel then the default channel is restored.

This call is utilized, for example, by the BASIC command DCLOSE.


3. $FF53 C64MODE  ;reconfigure system as a C64

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     none

               Flags:      none

         Example:

               JMP $FF53   ;switch to C64 mode

THERE IS NO RETURN FROM THIS ROUTINE. The system downloads code to RAM
which  reMAPs  the  system  to  put the C64 ROM in context, resets all
VIC-III modes, and jumps to the C64 start routine.

Return  to  C65  mode  is by resetting the machine, although a program
could  do  it  very  easily.  A  vector on the C64 side is provided to
restart C64DX mode.


4. $FF56 MonitorCall  ;enter Monitor mode

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     none

               Flags:      none

Turns  off  BASIC receipt of IRQ, maps BASIC out, maps the Monitor in,
and calls it.

When  the  Monitor is exited, the system is restored, BASIC mapped in,
and  the  system_vector  taken  (usually  points  to  BASIC warm start
entry).


5. $FF59 BOOT_SYS  ;boot an alternate OS from disk

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  undefined

               Memory:     undefined

               Flags:      undefined

Boot  an  alternate  system.  Reads  the "home" sector of any diskette
(physical track 0  sector 1,  512 bytes) into memory at $00400,  turns
off  BASIC,  and JMPs to it. Nothing done if disk not present. JMP not
made if first byte is not $4C.

It forces the "system" memory map, not user environment.

No  support for C128-style BOOT sector. Not related to BASIC 10.0 BOOT
command, which RUNs a BASIC program called "AUTOBOOT.C65*" if found.


6. $FF5C PHOENIX  ;???? C64DX diagnostics ????

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  undefined

               Memory:     undefined

               Flags:      none

         Example:

               JSR $FF5C   ;PHOENIX

Not same thing as C128 Phoenix routine. In the C65 development system,
this  routine  is  called  after  BASIC inits and performs some system
diagnostics, displaying results on the screen.


7. $FF5F LKUPLA  ;search tables for given la
8. $FF62 LKUPSA  ;search tables for given sa

         Preparation:

               Registers:  .A = LA (logical file number)
                                if LKUPLA

                           .Y = SA (secondary address)
                                if LKUPSA

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A = LA (only if found)
                           .X = FA (only if found)
                           .Y = SA (only if found)

               Memory:     none

               Flags:      .C = 0 if found
                           .C = 1 if not found

         Example:

               LDY #$60     ;find an available SA
         again INY
               CPY #$6F
               BCS too_many ;too many files open
               JSR $FF62    ;LKUPSA
               BCC again    ;get another if in use

LKUPLA  and  LKUPSA  are  Kernel  routines used primarily by BASIC DOS
commands  to  work  around  a  user's  open  disk channels. The Kernel
requires  unique  logical  device  numbers (LAs) and the disk requires
unique   secondary   addresses   (SAs),   therefore  BASIC  must  find
alternative  unused  values  whenever  it  needs  to  establish a disk
channel.


9. $FF65 SWAPPER  ;switch between 40 & 80 column modes

         Preparation:

               Registers:  none

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used
                           .Y used

               Memory:     screen cleared

               Flags:      none

         Example:

               LDA $D7     ;check display mode
               BMI if_80   ;branch if 80 column
               JSR $FF5F   ;switch from 40 to 80

MODE,  location  $D7,  is  toggled  by SWAPPER to indicate the current
display  mode: $80 = 80-column, $00 = 40-column. Because they are both
VIC  screens,  changing  them requires clearing the screens since they
share the same memory location.


10. $FF68 PFKEY  ;program a function key

         Preparation:

               Registers:  .A = pointer to string adr
                                (lo/hi/bank)
                           .Y = string length
                           .X = key number (1-16)

               Memory:     system map

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A used
                           .X used
                           .Y used

               Memory:     PKYBUF, PKYDEF tables updated

               Flags:      .C = 0 if successful
                           .C = 1 if no room

         Example:

               LDA #$FA    ;pointer to string address
               LDY #6      ;length
               LDX #15     ;key # ('HELP' key)
               JSR $FF68   ;install new key def'n
               BCS no_room

               >000FA 00 13 00           ;ptr to $1300 bank 0

               >01300 53 54 52 49 4E 47  ;'string'

PFKEY  (alias  KEYSET)  is an Editor utility to replace a function key
string with a user's string. Keys 1-14 are F1-F14, 15 is the HELP key,
and  16  is  the  <shift>RUN  string.  The  example above replaces the
'help<cr>'  string  assigned  at system initialization to the HELP key
with   the   string  'string'.  Both  the  key  length  table,  PKYBUF
($1000-$100F),  and  the  definition  area,  PKYDEF  ($1010-$10FF) are
compressed  and  updated.  The maximum length of all 16 strings is 240
characters.  No change is made if there is insufficient room for a new
definition.


11. $FF6B SETBNK  ;set bank for I/O operations
                  ;and filename

         Preparation:

               Registers:  .A = BA, memory bank (0-FF)
                           .X = FNBANK, filename bank

               Memory:     system map

               Flags:      none

               Calls:      SETNAM

         Results:

               Registers:  none

               Memory:     BA, FNBANK updated

               Flags:      none

         Example:

               see OPEN

SETBNK  is  a  prerequisite  for any memory I/O operations and must be
used  along  with  SETLFS  and  SETNAM prior to OPENing files, etc. BA
($C6)  sets  the  current  64KB  memory  bank  for  LOAD/SAVE/  VERIFY
operations.  FNBANK  ($C7)  indicates  the  bank in which the filename
string  is  found.  The Kernel routine SETBNK is often used along with
SETNAM and SETLFS calls prior to OPENs. See the Kernel OPEN, LOAD, and
SAVE calls for examples.


12. $FF6E JSRFAR  ;gosub in another bank
13. $FF71 JMPFAR  ;goto another bank

         Preparation:

               Registers:  none

               Memory:     system map, also:
                           $02 --> bank (0-FF)
                           $03 --> PC_high
                           $04 --> PC_low
                           $05 --> .S (status)
                           $06 --> .A
                           $07 --> .X
                           $08 --> .Y
                           $09 --> .Z

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     as per call, also:
                           $05 --> .S (status)
                           $06 --> .A
                           $07 --> .X
                           $08 --> .Y
                           $09 --> .Z

               Flags:      none

The  two  routines,  JSRFAR  and  JMPFAR, enable code executing in the
system bank of memory to call (or JMP to) a routine in any other bank.
In  the case of JSRFAR, the called routine must restore the system map
before executing a return.

JSRFAR  calls  JMPFAR. Both are RAM routines, located at $39C and $3B1
respectively.

The  user  should take necessary precautions when calling a non-system
bank  that  interrupts  (IRQs  &  NMIs)  will  be handled properly (or
disabled beforehand).


14. $FF74 LDA_FAR  ;LDA (.X),Y from bank .Z

         Preparation:

               Registers:  .X = pointer to base page pointer
                           .Y = index
                           .Z = bank (0-FF)

               Memory:     setup indirect vector

               Flags:      none

               Calls:      none

         Results:

               Registers:  .A = data

               Memory:     DMA_LIST updated

               Flags:      status valid

LDA_FAR  enables  applications  to  read  data from any other bank. It
builds  a  DMA_LIST to fetch one byte, executes the DMA, and reads the
byte. It's a ROM routine.


15. $FF77 STA_FAR  ;STA (.X),Y from bank .Z

         Preparation:

               Registers:  .A = data
                           .X = pointer to base page pointer
                           .Y = index
                           .Z = bank (0-FF)

               Memory:     setup indirect vector

               Flags:      none

               Calls:      none

         Results:

               Registers:  .X used

               Memory:     DMA_LIST updated

               Flags:      status invalid

STA_FAR  enables  applications  to  write  data  to any other bank. It
builds  a DMA_LIST to stash one byte, and executes the DMA. It's a ROM
routine.


16. $FF7A CMP_FAR  ;CMP (.X),Y from bank .Z

         Preparation:

               Registers:  .A = data
                           .X = pointer to a base page pointer
                           .Y = index
                           .Z = bank (0-FF)

               Memory:     setup indirect vector

               Flags:      none

               Calls:      none

         Results:

               Registers:  .X used

               Memory:     none

               Flags:      status valid

CMP_FAR  enables  applications  to  compare data to any other bank. It
builds  calls  LDA_FAR  and  compares  the  given  byte  with the byte
fetched. It's a ROM routine.


17. $FF7D PRIMM  ;print immediate utility

         Preparation:

               Registers:  none

               Memory:     none

               Flags:      none

               Calls:      none

         Results:

               Registers:  none

               Memory:     none

               Flags:      none

         Example:

               JSR $FF7D       ;display following text

               .BYTE 'message'
               .BYTE $00       ;terminator

               JMP continue    ;execution resumes here

PRIMM is a Kernel utility used to print (to the default output device)
a  PETSCII string which immediately follows the call.  The string must
be  no  longer  than  255 characters and be terminated by a null ($00)
character.  It  cannot  contain  any embedded null characters. Because
PRIMM  uses  the system stack to find the string and a return address,
you MUST NOT JMP to PRIMM. There must be a valid address on the stack.



3.4.6. BASIC 10.0 MATH PACKAGE

This document details the many user-callable routines available in the
C64DX BASIC 10.0 math package.


FLOATING POINT MATH PACKAGE CONVENTIONS

In BASIC memory the number is PACKED and looks like this:

             +--------+---------+--------+--------+-----+
             | signed | B7=SGN  |        |        |     |
             |   EXP  +---------+ M A N T I S S A | LSB |
             |  +$80  |   MSB   |        |        |     |
             +--------+---------+--------+--------+-----+

Because  the  mantissa  is  normalized  such that its msb is always 1,
BASIC  stores  the  SIGN  of  the  mantissa  here  to  save  a byte of
storage.  It  must be normalized when put in the FACC (see CONUPK). In
the FACC the NORMALIZED number looks like this:

            $63       $64      $65      $66     $67    $68
           FACEXP    FACHO    FACMOH   FACMO   FACLO  FACSGN

         +--------+---------+--------+--------+-----+-------+
         | signed | BIT 7=1 |        |        |     | SIGN  |
         |   EXP  +---------+ M A N T I S S A | LSB |+ = $00|
         | +$80   |   MSB   |        |        |     |- = $00|
         +--------+---------+--------+--------+-----+-------+

Negative exponents are not stored 2's complement. The maximum exponent
is  10^38  ($FF) and the minimum is 10^-39 ($01). A zero value for the
exponent means the number is zero. Since the exponent is a power of 2,
it  can  be  described  as  the  number  of  left  (EXP>$80)  or right
(EXP<=$80) shifts to be performed on the normalized mantissa to create
the  binary  representation  of  the value. There is a second floating
accumulator called ARG which has the same layout. It is located at $6A
through $6F. Throughout the math package the floating point format is:

  * the mantissa is 24 bits long.

  * the binary point is to the left of the msb.

  * the mantissa is always positive, and its msb is always 1.

  * number = mantissa * 2^exponent, sign in FACSGN.

  * the sign of the exponent is the msb of the exponent.

  * the exponent is stored in excess $80 (i.e., it is a signed
    8-bit number with $80 added to it.)

  * an exponent of zero means the number is zero. (Note that
    the rest of the accumulator cannot be assumed to be zero.)

  * to keep the same number in the accumulator while shifting:
        right shifts --> increment exponent
        left shifts  --> decrement exponent

Arithmetic routine calling conventions:

  * For one argument functions:
    the argument is in the FACC.
    the result is left in the FACC.

  * For two argument operations:
    the first argument is in MEMORY (packed) or ARG (unpacked).
    the second argument is in the FACC.
    the result is left in the FACC.

  * Always call ROM routines with SYSTEM memory in context (BANK $FF).

A  note concerning precision. Since the mantissa is always normalized,
the  high  order  bit of the most significant byte is always one. This
guarantees  at  least  40  bits (5 byte mantissa times 8 bits each) of
precision, which is approximately 9 significant digits plus a few bits
for  rounding. In fact, there is a 'rounding' byte, FACOV ($71), which
should,  for  the greatest degree of precision, be loaded whenever you
load  the FACC. The high order bit of FACOV is utilized in most of the
math  routines.  While  some  of  the  'movement' routines 'round' the
loaded  floating  point  number  (i.e.,  FACOV = $00), others (such as
CONUPK)  do  not - assuming the value of FACOV is the useful result of
an operation in progress. In 99% of the cases you need not worry about
it,  as  its significance is virtually nil. For the greatest degree of
precision however, use it.

A few examples of normalized (FACC) floating point numbers:

 VALUE          EXP          M A N T I S S A           SIGN
-------        -----    --------------------------     ----
 1E38   =       FF      96      76      99      53      00
 4E10   =       A4      95      02      F9      00      00
 2E10   =       A3      95      02      F9      00      00
 1E10   =       A4      95      02      F9      00      00
   10   =       84      A0      00      00      00      00
    1   =       81      80      00      00      00      00
   .5   =       80      80      00      00      00      00
  .25   =       7F      80      00      00      00      00
   .6   =       80      99      99      99      9A      00
1E-04   =       73      D1      B7      59      59      00
1E-37   =       06      88      1C      EA      15      00
1E-38   =       02      D9      C7      DC      EE      00
3E-39   =       01      82      AB      1E      2A      00
    0   =       00      xx      xx      xx      xx      00
   -1   =       81      80      00      00      00      FF
   -5   =       83      A0      00      00      00      FF

Now for a simple example of deriving the actual binary from the FACC:

    5   =       83      A0      00      00      00      00
                 |        \
                 |         \
              ($83-$80)   ($A0)
                 |
which means:   2^3   *  .10110000, or shift mantissa LEFT 3,

which gives:    101.00000 (binary) or 5.0 (hex)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           AYINT
FUNCTION:       CONVERT FLOATING POINT TO INTEGER

PREPARATION:    FACC contains floating point number (-32768<=n<=32767)

RESULT:         FACMO ($66) contains signed integer (msb)
                FACLO ($67) contains signed integer (lsb)

ERROR:          ?ILLEGAL QUANTITY ERROR if FACC too big.

EXAMPLE:        JSR AYINT      ;INT(FACC)
                LDA $66        ;MSB
                LDA $67        ;LSB

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           GIVAYF
FUNCTION:       CONVERT INTEGER TO FLOATING POINT

PREPARATION:    .A contains signed integer (msb)
                .Y contains signed integer (lsb)

RESULT:         FACC contains floating point number

EXAMPLE:        LDA #>INTEGER
                LDY #<INTEGER
                JSR GIVAYF     ;FLOAT (A,Y)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FOUT
FUNCTION:       CONVERT FLOATING POINT TO ASCII STRING

PREPARATION:    FBUFFR ($100) contains ASCII string (null terminated)
                .A contains pointer to string (lsb)
                .Y contains pointer to string (msb)

EXAMPLE:        JSR FOUT       ;CONVERT FACC TO STRING AT $100

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           VAL_1
FUNCTION:       CONVERT ASCII STRING TO FLOATING POINT

PREPAPATION:    INDEX1 ($24,$25) contains pointer to string
                .A contains length of string

SPECIAL NOTES:  String *MUST* be in var bank. Any invalid character
                terminates conversion when encountered (i.e., acts
                like a terminator).

RESULT:         FACC contains floating point number

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER
                STA INDEX1     ;SET POINTER TO STRING
                STY INDEX1+1
                LDA #LENGTH    ;SET STRING LENGTH
                JSR VAL_1      ;FACC = VAL(STRING)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           GETADR
FUNCTION:       CONVERT FLOATING POINT TO ADDRESS

PREPARATION:    FACC contains floating point number (0<=n<=65535)

RESULT:         POKER ($16,$17) contains unsigned integer address

ERROR:          ?ILLEGAL QUANTITY ERROR if FACC too big.

EXAMPLE:        JSR GETADR     ;ADR(FACC)
                LDA $16        ;LSB
                LDA $17        ;MSB

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FLOATC
FUNCTION:       CONVERT ADDRESS TO FLOATING POINT

PREPARATION:    FACHO  ($64) contains address (msb)
                FACMOH ($65) contains address (lsb)
                .X contains exponent ($90 always)
                .C=1 if positive (always)

RESULT:         FACC contains floating point number

ERROR:          ?OVERFLOW ERROR if FACC too big.

EXAMPLE:        LDA #<ADDRESS
                LDY #>ADDRESS
                STA FACMOH     ;SET ADDRESS
                STY FACHO
                LDY #$90       ;EXPONENT
                SEC            ;POSITIVE
                JSR FLOATC     ;FLOAT ADDRESS

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FSUB
FUNCTION:       FACC = MEMORY - FACC

PREPARATION:    FACC contains floating point subtrahend
                .A = pointer (lsb) to packed floating point minuend
                .Y = pointer (msb) to packed floating point minuend

SPECIAL NOTES:  The minuend *MUST* be in VARBANK in packed
                format. FSUB calls CONUPK to normalize it.

RESULT:         FACC contains floating point difference

ERROR:          ?OVERFLOW ERROR if FACC too big.

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* MINUEND
                JSR FSUB       ;SUBTRACT MEM FROM FACC, DIFF IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FSUBT
FUNCTION:       FACC = ARG - FACC

PREPARATION:    FACC contains floating point subtrahend
                ARG contains floating point minuend

SPECIAL NOTES:  This routine is similar to FSUB. The only difference
                is the call to CONUPK. (FSUBT assumes you have
                already loaded ARG with unpacked minuend.)

RESULT:         FACC contains floating point difference

ERROR:          ?OVERFLOW ERROR if FACC too big.

EXAMPLE:        JSR FSUBT      ;SUBTRACT ARG FROM FACC, DIFF IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FADD
FUNCTION:       FACC = MEMORY + FACC

PREPARATION:    FACC contains floating point addend
                .A = pointer (lsb) to packed floating point addend
                .Y = pointer (msb) to packed floating point addend

SPECIAL NOTES:  The second addend *MUST* be in VARBANK in
                packed format. FADD calls CONUPK to normalize it.

RESULT:         FACC contains floating point sum

ERROR:          ?OVERFLOW ERROR if result too big

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* ADDEND
                JSR FADD       ;ADD MEMORY TO FACC, SUM IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FADDT
FUNCTION:       FACC = ARG + FACC

PREPARATION:    FACC contains floating point addend
                ARG  contains floating point addend
                ARISGN  ($70) contains EOR(FACSGN,ARGSGN)
                .A   contains FACEXP

SPECIAL NOTES:  This routine is similar to FADD. The only
                difference is the call to CONUPK.

                *********************************************
                * You *MUST* put resultant sign in ARISGN.  *
                * You *MUST* load FACEXP ($63) immediately  *
                * before call so that status flags are set! *
                *********************************************

RESULT:         FACC contains floating point sum

ERROR:          ?OVERFLOW ERROR if result too big

EXAMPLE:        LDA FACSGN
                EOR ARGSGN
                STA ARISGN     ;SET RESULTANT SIGN
                LDA FACEXP     ;SET STATUS FLAGS PER FACEXP
                JSR FADDT      ;ADD ARG TO FACC, SUM IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FMULT
FUNCTION:       FACC = MEMORY * FACC

PEPARATION:     FACC contains floating point multiplier
                .A = pointer (lsb) to packed float. point multiplicand
                .Y = pointer (msb) to packed float. point multiplicand

SPECIAL NOTES:  The multiplicand *MUST* be in VARBANK in
                packed format. FMULT calls CONUPK to normalize it.

RESULT:         FACC contains floating point product

ERROR:          ?OVERFLOW ERROR if result too big

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* MULTIPLICAND
                JSR FMULT      ;MULTIPLY MEM BY FACC, PRODUCT IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FMULTT
FUNCTION:       FACC = ARG * FACC

PREPARATION:    FACC contains floating point multiplier
                ARG  contains floating point muitiplicand

SPECIAL NOTES:  This routine is similar to FMULT. The only difference
                is the call to CONUPK. (FMULTT assumes you have
                already loaded ARG with unpacked multiplicand.)

RESULT:         FACC contains floating point product

ERROR:          ?OVERFLOW ERROR if result too big

EXAMPLE:        JSR FMULTT     ;MULTIPLY ARG BY FACC, PRODUCT IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FDIV
FUNCTION:       FACC = MEMORY / FACC

PREPARATION:    FACC contains floating point divisor
                .A = pointer (lsb) to packed floating point dividend
                .Y = pointer (msb) to packed floating point dividend

SPECIAL NOTES:  The dividend *MUST* be in VARBANK in packed
                format. FDIV calls CONUPK to normalize it.

RESULT:         FACC contains floating point quotient

ERROR:          ?DIVISION BY ZERO ERROR if FACC zero

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* DIVIDEND
                JSR FDIV       ;DIVIDE MEM BY FACC, QUOTIENT IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FDIVT
FUNCTION:       FACC = ARG / FACC

PREPARATION:    FACC contains floating point divisor
                ARG  contains floating point divldend
                ARISGN ($70) contains EOR(FACSGN,ARGSGN)
                .A contains FACEXP

SPECIAL NOTES:  This routine is similar to FDIV. The only difference
                is the call to CONUPK. (FDIVT assumes you have
                already loaded ARG with unpacked dividend.)

                *********************************************
                * You *MUST* put resultant sign in ARISGN.  *
                * You *MUST* load FACEXP ($63) immediately  *
                * before call so that status flags are set! *
                *********************************************

RESULT:         FACC contains floating point quotient

ERROR:          ?DIVISION BY ZERO ERROR if FACC zero

EXAMPLE:        LDA FACSGN
                EOR ARGSGN
                STA ARISGN     ;SET RESULTANT SIGN
                LDA FACEXP     ;SET STATUS FLAGS PER FACEXP
                JSR FDIVT      ;DIVIDE ARG BY FACC, QUOTIENT IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           LOG
FUNCTION:       FACC = LOG(FACC)      natural logarithm (base e)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains floating point logarithm

ERROR:          ?ILLEGAL QUANTITY ERROR if FACC negative or zero

EXAMPLE:        JSR LOG        ;FACC = LOG(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           INT
FUNCTION:       FACC = INT(FACC)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains floating point greatest integer

EXAMPLE:        JSR INT        ;FACC = INT(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           SQR
FUNCTION:       FACC = SQR(FACC)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains floating point square root

ERROR:          ?ILLEGAL QUANTITY ERROR if FACC negative

EXAMPLE:        JSR SQR        ;FACC = SQR(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           NEGOP
FUNCTION:       FACC = -FACC          (invert sign of FACC)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains floating point number with sign inverted

EXAMPLE:        JSR NEGOP       ;FACC = -FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FPWR
FUNCTION:       FACC = ARG ^ MEMORY

PREPARATION:    ARG contains floating point number
                .A = pointer (lsb) to packed floating point power
                .Y = pointer (msb) to packed floating point power

SPECIAL NOTES:  The power *MUST* be in ROM or SYSTEM RAM in packed
                format as FPWR calls MOVFM to unpack it into FACC.

RESULT:         FACC contains floating point result

ERROR:          ?ILLEGAL QUANTITY ERROR if ARG negative
                ?OVERFLOW ERROR if result too big

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* POWER
                JSR FPWR       ;COMPUTE ARG ^ MEM, RESULT IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FPWRT
FUNCTION:       FACC = ARG ^ FACC

PREPARATION:    ARG  contains floating point number
                FACC contains floating point power
                .A   contains FACEXP

SPECIAL NOTES:  This routine is similar to FPWR. The only difference
                is the call to MOVFM. (FPWRT assumes you have already
                loaded FACC with unpacked power.)

                *********************************************
                * You *MUST* load FACEXP ($63) immediately  *
                * before call so that status flags are set! *
                *********************************************

RESULT:         FACC contains floating point result

ERROR:          ?ILLEGAL QUANTITY ERROR if ARG negative
                ?OVERFLOW ERROR if result too big

EXAMPLE:        LDA FACEXP     ;SET STATUS FLAGS PER FACEXP
                JSR FPWRT      ;COMPUTE ARG ^ FACC, RESULT IN FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           EXP                   (compute e ^ FACC)
FUNCTION:       FACC = EXP (FACC)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains fIoating point result

ERROR:          ?OVERFLOW ERROR if FACC too big

EXAMPLE:        JSR EXP        ;FACC = EXP(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           COS
FUNCTION:       FACC = COS(FACC)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains floating point cosine (in radians)

EXAMPLE:        JSR COS        ;FACC = COS(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           SIN
FUNCTION:       FACC = SIN(FACC)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains floating point sine (in radians)

EXAMPLE:        JSR SIN        ;FACC = SIN(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           TAN
FUNCTION:       FACC = TAN(FACC)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains floating point tangent (in radians)

EXAMPLE:        JSR TAN        ;FACC = TAN(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           ATN
FUNCTION:       FACC = ATN(FACC)

PREPARATION:    FACC contains floating point number

RESULT:         FACC contains floating point arctangent (in radians)

EXAMPLE:        JSR ATN        ;FACC = ATN(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           ROUND            (round to 40 bits of precision)
FUNCTION:       FACC = FACC + FACOV(msb)

PREPARATION:    FACC contains floating point number
                FACOV(msb) contains 'extra' precision

RESULT:         none if FACC zero or FACOV(msb) zero
                one extra bit ADDED to FACC lsb if FACOV(msb) is set

EXAMPLE:        JSR ROUND      ;ROUND FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           ABS                     (make FACSGN(msb) = $00)
FUNCTION:       FACC = ABS(FACC)

PREPARATION:    FACC contains (SIGNED) floating point number

RESULT:         FACC contains (POSITIVE) floating point

EXAMPLE:        JSR ABS        ;FACC = ABS(FACC)

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           SGN
FUNCTION:       .A = SGN(FACC)

PREPARATION:    FACC contains floating point number

RESULT:         .A --> $FF if FACC negative (FACC < 0)
                       $00 if FACC zero     (FACC = 0)
                       $01 if FACC positive (FACC > 0)
                (status flags reflect contents of .A, carry invalid)

EXAMPLE:         JSR SGN       ;SGN(FACC)
                               ; BEQ will trap =0
                               ; BNE will trap <>0
                               ; BMI will trap <0
                               ; BPL will trap >=0     etc.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           FCOMP                 (compare FACC with MEMORY)
FUNCTION:       .A = FCOMP(FACC,MEMORY)

PREPARATION:    FACC contains floating point number
                .A = pointer (lsb) to packed floating point number
                .Y = pointer (msb) to packed floating point number

SPECIAL NOTES:  The number *MUST* be in ROM, or RAM currently in
                context below ROM, in PACKED format.
                *** FACOV is significant!

RESULT:         .A --> SFF if FACC < MEMORY
                       $00 if FACC = MEMORY
                       $01 if FACC > MEMORY
                (status flags reflect contents of .A, carry invalid)

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* NUMBER
                JSR FCOMP      ;COMPARE FACC WITH MEMORY
                               ; BEQ will trap FACC =  MEM
                               ; BNE will trap FACC <> MEM
                               ; BMI will trap FACC <  MEM
                               ; BPL will trap FACC >= MEM    etc.

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           RND0
FUNCTION:       FACC = random floating point number (0<n<1)

PREPARATION:    .A --> $00 to generate a 'true' random number
                       $01 to generate next random number in sequence
                       $FF to start a new sequence of random numbers
                           based upon current contents of FACC.

SPECIAL NOTES:  *MUST* be called with the system bank in context.
                *MUST* load .A immediately before call so that status
                flags reflect contents of .A

RESULT:         FACC = floating point random number

EXAMPLE:        LDA #$FF  ;START REPRODUCEABLE SEQUENCE BASED ON FACC
                JSR RND0
                LDA #$01
                JSR RND0  ;GENERATE (FIRST) RANDOM NUMBER IN SEQUENCE

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           CONUPK
FUNCTION:       ARG = UNPACK(RAM_CONSTANT)

PREPARATION:    .A = pointer (lsb) to packed floating point number
                .Y = pointer (msb) to packed floating point number

SPECIAL NOTES:  The number *MUST* be in VARBANK or SYSTEM RAM in
                packed format.

RESULT:         ARG    loaded with normalized floating point number
                ARISGN ($6F) contains EOR(FACSGN,ARGSGN)
                .A   contains FACEXP (status reflects contents of .A)

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* NUMBER
                JSR CONUPK     ;LOAD ARG
                               ; BEQ traps ARG = $00

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           ROMUPK
FUNCTION:       ARG = UNPACK(ROM_CONSTANT)

PREPARATION:    .A = pointer (lsb) to packed floating point number
                .Y = pointer (msb) to packed floating point number

SPECIAL NOTES:  The number *MUST* be in ROM or SYSTEM RAM currently
                in context (otherwise identical to CONUPK).

RESULT:         ARG    loaded with normalized floating point number
                ARISGN ($6F) contains EOR(FACSGN,ARGSGN)
                .A   contains FACEXP (status reflects contents of .A)

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* NUMBER
                JSR ROMUPK     ;LOAD ARG
                               ; BEQ traps ARG = $00

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           MOVFRM
FUNCTION:       FACC = UNPACK(RAM_CONSTANT)

PREPARATION:    .A = pointer (lsb) to packed floating point number
                .Y = pointer (msb) to packed floating point number

SPECIAL NOTES:  The number *MUST* be in VARBANK or SYSTEM RAM in
                packed format.

RESULT:         FACC  loaded with normalized floating point number
                FACOV ($71) cleared

EXAMPLE:        LDA #<POINTER
                LDY #>POINTER  ;SET POINTER TO *PACKED* NUMBER
                JSR MOVFRM     ;LOAD FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           MOVFA
FUNCTION:       FACC = ARG

PREPARATION:    ARG contains floating point number

RESULT:         FACC  contains same number as ARG
                FACOV ($71) cleared
                .A    contains FACEXP (but status invalid!)

EXAMPLE:        JSR MOVFA      ;COPY ARG TO FACC

=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-

NAME:           MOVAF
FUNCTION:       ARG = FACC

PREPARATION:    FACC contains floating point number

RESULT:         FACC will be ROUNDed and FACOV cleared.
                ARG  contains same number as FACC
                .A   contains FACEXP (but status invalid!)

EXAMPLE:        JSR MOVAF      ;COPY FACC TO ARG



3.5. C65 DOS Documentation

                     DIRECTORY HEADER DEFINITION
----------------------------------------------------------------------
  BYTE                           DESCRIPTION
 ------ --------------------------------------------------------------
   0      TRACK mumber which points to the 1st dir. sector
   1      SECTOR number which points to the 1st dir. sector
   2      Disk format version number, which is currently 'D'
              512 byte sectors 20 per track
              20 Sectors per track
              40 Tracks per side
              2 sides (note they're inverted from normal MFM disk)
   3      Must = 0
   4      Bytes 4 thru 21 contain the volume name (label)
  22      Bytes 22 and 23 contain the disk id (fake)
  24      Must contain an $A0
  25      DOS version number (CBMDOS = 1, 1581 = 3)
  26      Format version number (currently = 'D' (fake))
  27      Bytes 27 thru 28 = $A0
  29      NOT USED AT THIS TIME
  30      NOT USED AT THIS TIME
  31      NOT USED AT THIS TIME
  32      NOT USED AT THIS TIME
  33      NOT USED AT THIS TIME
  34      Track number which points to this directory header
  35      Sector number which points to this directory header
  36      Bytes 36 thru 255 are not used at this time

NOTE:  If  this  is a subdirectory header then BYTES 32 and 33 contain
the  TRACK & SECTOR number of the DIRECTORY SECTOR that points to this
DIRECTORY HEADER.  See the partition command for a better description.
If this is the ROOT header then they will contain a $00.


                            BAM DEFINITION
----------------------------------------------------------------------
  BYTE                           DESCRIPTION
 ------ --------------------------------------------------------------
   0      Track link for next bam sector, if last then end of BAMs
   1      Sector link
   2      Format type this disk was formatted under
   3      Compliment version number of byte 2 above
  4-5     Disk ID used when this disk was formatted
   6      I/O byte used as follows;
            BIT 7- When set Verify is performed after each disk write
            BIT 6- Perform CRC check (not used by CBDOS)
            BIT 1- Huge relative files disabled
   7      Auto loader flag (not used by CBDOS)
  8-15    Not used at this time by any CBM DOS versions
 16-255   BAM image


                              BAM IMAGE
----------------------------------------------------------------------
  BYTE                           DESCRIPTION
 ------ --------------------------------------------------------------
   0      Number of free sectors on this track
   1      MSB flag for sector  7, LSB flag for sector  0
   2      MSB flag for sector 15, LSB flag for sector  8
   3      MSB flag for sector 23, LSB flag for sector 16
   4      MSB flag for sector 31, LSB flag for sector 24
   5      MSB flag for sector 39, LSB flag for sector 32


                     DIRECTORY SECTOR DEFINITION
----------------------------------------------------------------------
  BYTE                           DESCRIPTION
 ------ --------------------------------------------------------------
   0      TRACK  -- Points to the next directory track.
   1      SECTOR -- Points to the next directory sector.
                 (IF TRACK = 0 THEN THIS IS THE LAST DIRECTORY SECTOR)


                        FILE ENTRY DESCRIPTION
----------------------------------------------------------------------
  BYTE                           DESCRIPTION
 ------ --------------------------------------------------------------
   0      File status byte which is used as follows:
          BIT 7- Set indicates properly closed file
          BIT 6- File is locked (read only)
          BIT 5- Save with replace is CURRENTLY in effect,
                 when file is closed this bit is deleted.
          BIT 4- NOT USED AT THIS TIME
          BIT 3- Bits 3 thru 0 are used to indicate the filetype:
                 0=DEL, 1=SEQ, 2=PRG, 3=USER, 4=REL, 5=CBM, 6=not used
                 7=used by dos to represent DIRECT type of file access
   1      TRACK - link to the 1st sector of data for this file.
   2      SECTOR - link to the 1st sector of data for this file.
   3      Bytes 3-18 contain the filename in ASCII, padded with $A0
  19      Side Sector TRACK link for relative files
            GEOS - Track number of GEOS file header
  20      Side Sector SECTOR link for relative files
            GEOS - Sector number of GEOS file header
  21      Record size for relative files
            GEOS - File structure type 0=SEQ, 1=VLIR
  22      GEOS - FILE TYPES:
          13 = Swap file     12 = System boot   11 = Disk device
          10 = Input device  09 = Printer       08 = Font
          07 = Appl. data    06 = Applications  05 = Desk Acc.
          04 = System        03 = Basic data    02 = Assembly
          00 = Not GEOS
  23      Not used by CBM DOS previous to CBDOS
            GEOS - DATE: Year last modified (offset from 1990)
            CBDOS- Bits 7-4 contain the upper 4 bit's from the
                   file type byte (see byte 0 above) for the
                   UNNEW, UNSRATCH commands used by CBDOS
  24      Not used by CBM DOS previous to CBDOS
            GEOS - DATE: Month last modified (1 thru 12)
            CBDOS- Bit's 7 thru 4 contain the lower 4 bit's from the
                   file type byte (see byte 23 above)
  25      GEOS - DATE: Day last modified (1 thru 31)
  26      TRACK (from 1) for the save with replace file
            GEOS - DATE: Hour last modified (0 thru 23)
  27      SECTOR (from 2) for the save with replace file
            GEOS - DATE: Minute last modified (0 thru 59)
  28      LSB of the # of sectors used by this file
  29      MSB of the # of sectors used by this file

NOTE: Each sector in the directory contains 8 entries of 32 bytes each.


                    SIDE SECTOR FORMAT DEFINITION
----------------------------------------------------------------------
  BYTE                           DESCRIPTION
 ------ --------------------------------------------------------------
   0      Next Side Sector TRACK  link ($FF if last)
   1      Next Side Sector SECTOR link
   2      Side Sector number
          If this is a SUPER SIDE SECTOR then this contains an $FE
          (see the description of the SUPER SIDE SECTOR below)
   3      Record Size
  4-5     TRACK & SECTOR link of Side Sector number 0
  6-7     TRACK & SECTOR link of Side Sector number 1
  8-9     TRACK & SECTOR link of Side Sector number 2
 10-11    TRACK & SECTOR link of Side Sector number 3
 12-13    TRACK & SECTOR link of Side Sector number 4
 14-15    TRACK & SECTOR link of Side Sector number 5
 16-17    TRACK & SECTOR link of the DATA BLOCK #0
 18-19    TRACK & SECTOR link of the DATA BLOCK #l
      etc...

NOTE: There are 91 groups to the largest file that this DOS can handle.


                SUPER SIDE SECTOR FORMAT DEFINITION
----------------------------------------------------------------------
  BYTE                           DESCRIPTION
 ------ --------------------------------------------------------------
   0      Next Side Sector TRACK link (SFF if last)
   1      Next Side Sector SECTOR
   2      Contains an SFE to indicate this is a SUPER SIDED SECTOR
  3-4     TRACK & SECTOR link of Side Sector number 0
  5-6     TRACK & SECTOR link of Side Sector number 1
  7-8     TRACK & SECTOR link of Side Sector number 2
  9-10    TRACK & SECTOR link of Side Sector number 3
 11-12    TRACK & SECTOR link of Side Sector number 4
 13-14    TRACK & SECTOR link of Side Sector number 5
 .....    ...........................................
253-254   TRACK & SECTOR link of Side Sector number 125

NOTE:There are 91 groups to the largest file that this DOS can handle.


                         DATA SECTOR DEFINITION
----------------------------------------------------------------------
  BYTE                           DESCRIPTION
 ------ --------------------------------------------------------------
  0-1     TRACK and SECTOR link to the next data block. If track=0
          then sector contains the number of bytes used in this
          sector (which will always be at least 2 on the last block
          for the T&S link bytes).

NOTE: Used by DEL, SEQ, PRG, REL (data blocks) and USR.


;*-------------------------------------------------------------------*
;* Format a track                                                    *
;* 10 sectors per track numbered 1-10, 512 byte sectors              *
;*-------------------------------------------------------------------*
;*  12 Sync marks                            00                      *
;*   3 Header ID marks w/missing clock       A1                      *
;*   1 Header ID                             FE                      *
;*   4 Header bytes                          Track                   *
;*                                           Side                    *
;*                                           Sector                  *
;*                                           Sector size             *
;*   2 Header CRC bytes                      xx,xx                   *
;*  22 Data gap bytes                        4E                      *
;*  12 Sync marks                            00                      *
;*   3 Data block ID marks w/missing clock   A1                      *
;*   1 Data block ID                         FB                      *
;* 512 Data block fill bytes                 00                      *
;*   2 Data block CRC bytes                  xx,xx                   *
;*  24 Sector gap bytes                      4E                      *
;*-------------------------------------------------------------------*

;*-------------------------------------------------------------------*
;* Calculate the 2 bytes CRC for each sector header of an entire     *
;* track of 10 sectors. AXYZ are trashed.                            *
;*                                                                   *
;*   This routine is based on the Cyclical Redundancy Check          *
;*   on the polynomial: A^16+A^12+A^5+1.                             *
;*                                                                   *
;*     HEADER contains TRACK,SIDE,SECTOR,2 [sector size]             *
;*                                                                   *
;*     DO WHILE ne = 0                                               *
;*       DO FOR each bit in the data byte (.a) [from lsb to msb]     *
;*         IF (LSB of crc) eor (LSB or data)                         *
;*           THEN CRC = (CRC/2) EOR polynomial                       *
;*         ELSE CRC = (CRC/2)                                        *
;*         END IF                                                    *
;*       LOOP                                                        *
;*     LOOP                                                          *
;*-------------------------------------------------------------------*

;*-------------------------------------------------------------------*
;*     SIDE           = (LogicalSector >= 20) AND 1                  *
;*     TRACK          = LogicalTrack - 1                             *
;*     StartingSector = SIDE * 20                                    *
;*     SECTOR         = (LogicalSector - StartingSector) / 2 + 1     *
;*     HALF           = (LogicalSector - StartingSector) AND 1       *
;*-------------------------------------------------------------------*


C65 Partition and Subdirectory Syntax

This  specification  describes a _proposed_ C65 partition/subdirectory
parser.

       OPEN la,fa,sa, "[#]/path/:filename"
       OPEN la,fa,15, "<cmd>#/path/:[cmd_string]"

where: #             is an optional "drive" number, 0-3.
       /path/        is a partition or subdirectory name
       :             delimits the path from the filename

and:   <cmd>         is a DOS command (such as I,N,S,C, etc.)
       (cmd_string)  is an optional string required by some commands.

The  first  example  illustrates a typical filename specification, the
second example illustrates a command channel instruction.

       OPEN la,fa,sa, "0/SUBDIR1/SUBDIR2/:FILE,S,W"

             Action taken                           Why
 ------------------------------------ -------------------------------
  1. Select the "root"                 0
  2. Find & enter two subdirectories   /SUBDIR1/SUBDIR2/:
                                       (the trailing "/" is required
                                       to be compatible with CMD?)
  3. Create & open file for writing    FILE,S,W

The "root" or "drive number", path, and ":" are all optional.  If they
are  omitted,  the  file  is  opened  in  the current partition.  Some
similar, and legal, syntaxes are:

  OPEN la,fa,sa, "FILE,S,W"           (create "FILE" in current part)
  OPEN la,fa,sa, ":FILE,S,W"          (create "FILE" in current part)
  OPEN la,fa,sa, "0:FILE,S,W"         (create "FILE" in current part)
  OPEN la,fa,sa, "/SUBDIR/ FILE,S,W"  (from current partition, enter
                                       "SUBDIR" and create "FILE")
  OPEN la,fa,sa, "//SUBDIR/:FILE,S,W" (from Root partition, enter
                                       "SUBDIR" and create "FILE")
  OPEN la,fa,sa, "@0/SUBDIR/:FILE"    (open "FILE" in "SUBDIR" for
                                       writing)

Some questionable syntaxes, and their affect, are:

  OPEN la,fa,sa, "0FILE,S,W"          (this would create file "0FILE")
  OPEN la,fa,sa, "/SUBDIR/FILE,S,W"   (creates file "/SUBDIR/FILE"
  OPEN la,fa,sa, "@0:FILE,S,W"        (open filr "FILE" in current
                                       partition for writing)
  OPEN la,fa,sa, "/0:FILE,S,W"        (? should create file "0:file",
                                       note this is not the cmd chnl)
Some legal commands:

  OPEN la,fa,sa,"I0"                  (initialize current partition)
  OPEN la,fa,sa,"I//"                 (initialize Root)
  OPEN la,fa,sa,"I0/SUBDIR/:"         (enter "SUBDIR" and initialize)
  OPEN la,fa,sa,"N0/SUBDIR/:NAME,ID"  (enter "SUBDIR" and "new" it)
  OPEN la,fa,sa,"S0/SUBDIR/:FILE"     (delete "FILE" in "SUBDIR")
  OPEN la,fa,sa,"/0:SUBDIR"           (1581 partition select, "/" in
                                       this context is a command
                                       itself)


Some  proposed general rules,  designed to be compatible with both the
1581 subpartitioning syntax and CMD syntax:

  1. The  name  of  a  subdirectory  must always be separated from the
     filename by a colon (":").

  2. Each subdirectory name must be delimited by a slash ("/").

  3. To select Root directory (partiton),  specify two slashes ("//").
     This allows older applications specifying the drive number ("0:")
     to be run in a partition.


                      CURRENT PARTITION ROUTINES

Create Partition:
       "/0:PAR_NAME,"+(START-TRK)+(START-SECTOR)+(LO-BLKS)+(HI-BLKS)

Select Partition:
       "/0:PAR_NAME"  will select given filname as subdirectory
       "/0"           will select root directory


                    SELECT PARTITION

This  routine  will  allow  the user to quickly select partition paths
using  the normal SA values other than 15.  To use this new method the
user  opens  the  file  using  a  normal  SA  and the filename MUST be
structured as follows:

       "/<drive>:PATH_1/PATH_2/PATH_3..... ETC"

If the dos does not find one of the filenames in the file path  stream
it will check to see if the file exists in the current  directory  and
if it does it will open the file in the normal method as it does now.


;*********************************************************************
;*                           FILE_COMMANDS                           *
;*                                                                   *
;* The following set of command channel routines were added to allow *
;* the user a graceful way of manipulating files:                    *
;*                                                                   *
;*      "F-L"  Locate a file to prevent it from being scratched      *
;*      "F-U"  Unlock a file and allow it to be scratched            *
;*      "F-R"  Restore a file after it has been scratched            *
;*                                                                   *
;* Following  each command above is the drive number,  followed by a *
;* colon then followed by the filename(s).  For example, to lock all *
;* the files on drive 0 you would send the following file command:   *
;*                                                                   *
;*             OPENXX,XX,15,"F-L0:*"                                 *
;*                                                                   *
;*             OPENXX,XX,15,"F-L0:FNAME,FNAME1,FNAME2,... ETC"       *
;*********************************************************************

;*********************************************************************
;*                           BLOCK STATUS                            *
;*                                                                   *
;* Syntax: "B-S:CHANNEL NUMBER, DRIVE NUMBER, TRACK, SECTOR"         *
;*                                                                   *
;* Then check error channel for normal errors then get one byte from *
;* from  the  channel number.  If it is a 0 then the sector is free. *
;* 1 indicates the sector is in use.                                 *
;*                                                                   *
;* This command was added to enable an easy method of finding out if *
;* a  given  track  or sector is currently marked as being used in a *
;* drive's BAM or not.                                               *
;*                                                                   *
;*                            CBDOS CHGUTIL                          *
;*                                                                   *
;*     COMMAND                  COMMENTS              DRIVES USED ON *
;* "U0>B"+chr$(n)  b  =  set fast/slow serial bus          1581      *
;* "U0>D"+chr$(n)  d  =  set dirsecinc                     CBDOS     *
;* "UO>H"+chr$(n)  h  =  set head selection 0,1            1571      *
;* "U0>M"+chr$(n)  m  =  set dos mode                      1571      *
;* "U0>R"+chr$(n)  r  =  set dos retries on errors      1571,1581    *
;* "UO>S"+chr$(n)  s  =  set secinc                  1571,1581,CBDOS *
;* "U0>V"+chr$(n)  v  =  set verify on/off              1581,CBDOS   *
;* "U0>?"+chr$(n)  ?  =  set device number                 CBDOS     *
;* "U0>L"+chr$(n)     =  set large rel files on/off        CBDOS     *
;* "U0>MR"+ xx        =  perform memory read               1581      *
;* "U0>MW"+ xx        =  perform memory write              1581      *
;*  12345                                                            *
;*      ^--------------- CMDSIZ points to end of starting string @1  *
;*********************************************************************


FLOPPY DISK CONTROLLER ERRORS

  IP  FDC  DESCRIPTION
  --  ---  -----------
  0   (0)  no error
  20  (2)  can't find block header
  23  (5)  checksum error in data
  25  (7)  write-verify error
  26  (8)  write w/ write protect on
  27  (9)  crc error in header

  Information description
  -----------------------
  1   files scratched
  2   selected partition
  3   files locked
  4   files unlocked
  5   files restored

  Parameter errors
  ----------------
  30  general syntax
  31  invalid command
  32  long line
  33  invalid filname
  34  no filenames given

  Relative file errors
  --------------------
  50  record not present
  51  overflow in record
  52  file too large
  53  big relative files disabled

  Open routine errors
  -------------------
  60  file open for write
  61  file not open
  62  file not found
  63  file exists
  64  file type mismatch

  Sector management errors
  ------------------------
  65  no block
  66  illegal track or sector
  67  illegal system t or s

  General channel/block errors
  ----------------------------
  02  channel selected
  70  no channels available
  71  bam corrupted error
  72  disk full
  73  cbdos v1.0
  74  drive not ready
  75  format error
  76  controller error
  77  selected partition illegal
  78  directory full
  79  file corrupted



3.6. C64DX RS-232 DRIVER

  00A7   rs232_status             - UART status byte
  00A8   rs232_flags              - open flag, xon/xoff status
                                  - b7: channel open      (reset)
                                  - b6: flow control      (1=x-line)
                                  - b5: duplex            (1=half)
                                  - b1: XOFF received
                                  - b0: XOFF sent
  00A9   rs232_jam                - system character to xmit
  00AA   rs232_xon_char           - XON character (null=disabled)
  00AB   rs232_xoff_char          - XOFF character (null=disabled)
  00B0   rs232_xmit_empty         - xmit buffer empty flag (0=empty)
  00B1   rs232_rcvr_buffer_lo     - lowest page of input buffer
  00B2   rs232_rcvr_buffer_hi     - highest page of input buffer
  00B3   rs232_xmit_buffer_lo     - lowest page of output buffer
  00B4   rs232_xmit_buffer_hi     - highest page of output buffer
  00B5   rs232_high_water         - point at which receiver XOFFs
  00B6   rs232_low_water          - point at which receiver XONs

  00C4   rs232_rcvr_head          - pointer to end of buffer
  00C6   rs232_rcvr_tail          - pointer to start of buffer
  00C8   rs232_xmit_head          - pointer to end of buffer
  00CA   rs232_xmit_tail          - pointer to start of buffer

                   RS-232 interrupt-driven handler

How  it  works:  when an RS232 channel is OPENed, buffers are flushed,
all flags and states are reset, and the receiver IRQ is enabled.  When
a byte is put into the xmit buffer by BSOUT,  the xmit IRQ is enabled.
The xmit IRQ is disabled whenever the xmit buffer is found to be empty
or  an  XOFF is received  (it is enabled whenever an XON is received).
CLOSE  will  hang until the xmit buffer is empty,  and BSOUT will hang
when the xmit buffer is full.  IRQs must be allowed by the user at all
times  (and especially during BSOUT calls) for proper operation.  (The
RS232  channel  will  work even if IRQs are disabled by the user,  but
thoughput will be reduced to the frame rate (normal system raster IRQ)
and the system can hang forever should the xmit buffer become full and
BSOUT is called with a byte to xmit).  A successful CLOSE will disable
all RS232 interrupts and re-init everything.

Note  that DOS calls disable both IRQ and NMI interrupts while the DOS
code is in context. The remote should be XOFFed to avoid loss of data.

Refer to the UART specification for register description  &  baud rate
tables.

                    Open an RS-232 channel

This is different from the usual C64/C128 command string.

                           1    2     3        4          5     6
Command string bytes:    baud|word|parity|stop(unused)|duplex|xline



4.0. C64DX DEVELOPMENT SOPPORT

Please  photocopy  the  attached  'C64DX PROBLEM REPORT' and use it to
report any problems.

If  you  have  any  requests  or recommendations,  please  send a good
description of it and explain why you want it.

+----------------------------------------+-------------------------------------+
|        C64 DX PROBLEM REPORT           | Date                                |
+----------------------------------------+-------------------------------------+
|Please complete this form as completely as possible and mail or express it to:|
|                                                                              |
| Commodore Business Machines, Inc.       Telephone: 215-431-9427              |
| 1200 Wilson Drive                       Fax:       215-431-9156              |
| West Chester,  PA    I9380              Email:     fred@cbmvax.commodore.com |
|                                                                              |
|                      Attention: Fred Bowen, Engineering                      |
+------------------------------------------------------------------------------+
|Company Name                                                                  |
+------------------------------------------------------------------------------+
|Company Address                                                               |
|                                                                              |
|                                                                              |
|                                                                              |
|                                                                              |
|                                                                              |
|                                                                              |
|                                                                              |
+----------------------------------------+-------------------------------------+
|Your Name                               |Your Phone                           |
+----------------------------------------+-------------------------------------+
|Your system                                                                   |
|                                                                              |
| Serial No.________ PCB rev_________ Software ver________ ROM Cksum__________ |
|                                                                              |
| 4510 rev__________ 4567 rev________ F011(DOS)___________ F018(DMA)__________ |
|                                                                              |
| Peripherals:                                                                 |
+---------------------+--------------------------------------------------------+
|Your problem         | Explain problem here and show how to cause it.  Attach |
|                     | sample program.                                        |
|  ____ C64 mode      |                                                        |
|  ____ C64DX mode    |                                                        |
|  ____ Hardware      |                                                        |
|  ____ Software      |                                                        |
|  ____ Mechanical    |                                                        |
|  ____ Documentation |                                                        |
|  ____ Compatibility |                                                        |
|                     | It happens:                                            |
|                     |  ____ all the time  ____ frequently  ____ occasionally |
+---------------------+--------------------------------------------------------+
|In your opinion, how I bad is the problem?      ____ Must fix, no workaround  |
|                                                                              |
|                                                ____ I can work around it     |
|                                                                              |
|  ____ Check here if you need to be contacted   ____ Minor problem            |
+------------------------------------------------------------------------------+
|Please leave this space blank                                                 |
|                                                                              |
|                                                                              |
|                                                                              |
|                                                                              |
|                                                                              |
|Number               Received               Contacted               Completed |
+------------------------------------------------------------------------------+



C64DX System Specification UPDATE


*   The Monitor parser now allows PETSCII input/conversion:

            'A                prints ASC() value of character
            >1800 'text       puts text into memory
            LDA #'A


*   IRQ  runs  during  graphics  (Kernel finds its own base page). IRQ
    still  does  not  run  during  DOS activity (not sure if they ever
    will).

*   The  following Kernel Jump Table Entries have moved (and are still
    subject to further changes):

         FF05    nirq              ;IRQ handler
         FF07    monitor_brk       ;BRK handler (Monitor)
         FF09    nnmi              ;NMI handler
         FF0B    nopen             ;open
         FF0D    nclose            ;close
         FF0E    nchkin            ;chkin
         FF11    nckout            :ckout
         FF13    nclrch            ;clrch
         FF15    nbasin            :basin
         FF17    nbsout            ;bsout
         FF19    nstop             ;stop key scan
         FF1B    ngetin            ;getin
         FF1D    nclall            ;clall
         FF1F    monitor_parser    ;monitor command parser
         FF21    nload             ;load
         FF23    nsave             ;save

         FF25    talk
         FF27    listen
         FF29    talksa
         FF2B    second
         FF2D    acptr
         FF2F    ciout
         FF31    untalk
         FF33    unlisten

         FF35    DOS_talk
         FF37    DOS_listen
         FF39    DOS_talksa
         FF3B    DOS_second
         FF3D    DOS_acptr
         FF3F    DOS_ciout
         FF41    DOS_untalk
         FF43    DOS_unlisten

         FF45    Get_DOS
         FF47    Leave_DOS
         FF49    ColdStartDOS      <<<new
         FF4B    WarmStartDOS      <<<new


2.1.2. German/Austrian Reyboard Layout

+----+   +----+----+----+----+   +----+----+----+----+   +----+----+----+----+
|RUN |   |ESC |ALT |ASC | NO |   | F1 | F3 | F5 | F7 |   | F9 | F11| F13|HELP|
|STOP|   |    |    |DIN |SCRL|   | F2 | F4 | F6 | F8 |   | F10| F12| F14|    |
+----+   +----+----+----+----+   +----+----+----+----+   +----+----+----+----+

+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+----+
|   <| !  | "  | # | $  | %  | &  | ' /| (  | )  |  " |  ? |  ` |  ^ |CLR |INST|
|  >| 1  | 2  | 3  | 4  | 5  | 6  | 7  | 8  | 9  | 0  | + | - '|  [|HOME|DEL |
+----+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+----+
|  TAB  |    |    |    |    |    |  Z |    |    |    |    |   |    |  \ | RSTR |
|       | Q  | W  | E  | R  | T  | Y  | U  | I  | O  | P  | @  | * +| ^ ]|      |
+----+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+------+
|CTRL|SHFT|    |    |    |    |    |    |    |    |    |   |   |  ' |  RETURN |
|    |LOCK| A  | S  | D  | F  | G  | H  | J  | K  | L  | : [| ; ]| = #|         |
+----+----+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+--+-+----+----+----+
| C= | SHIFT |  Y |    |    |    |    |    |    | < ;| > :| ? _| SHIFT|    |
|    |       | Z  | X  | C  | V  | B  | N  | M  | ,  | .  | / -|      |   |
+----+-------+-+--+----+----+----+----+----+----+----+----+-+--+-+----+----+----+
               |                                            |    |    |    |    |
               |                                            |    |   |   |   |
               +--------------------------------------------+    +----+----+----+


Notes:

1/ The   operation   of   national  keyboards  is  identical  to  C128
   implementation.  The ASCII/DIN key replaces the CAPS LOCK key,  and
   can  be  toggled anytime to switch keyboard modes and automatically
   change the display.

2/ The  national  keyboard  contains key legends for both national and
   ASCII modes. The national legends appear on the right top/bottom of
   the keys.

3/ The  German  keyboard  has  three  (3) "deadkeys".  They are accent
   d'aigue,   accent  grave,  and  accent  circonflex.   Pressing  the
   "deadkey"  followed  by  a  valid  vowel  or  accent character will
   'build' the desired character:

         accent d'aigue:      
         accent grave:        , , 
         accent circonflex:   , , , ", 

4/ National  character  ROM graphic characters differ from the C64 and
   ASCII (English) graphic character sets.


PAINT x, y [,color]
               Working,  but  not  completely  to spec.  Uses draw pen
               color and fills emptyness to any border.

RND(0)         Improved  for  better "randomness".  Uses unused POT of
               second SID chip. PCB must allow lines to float.


SET DISK #     (without [TO #] parameter)  allows  user  to  clear DS$
               message and specify which drive next DS$ comes from.

SET VERIFY <ON/OFF>
               The new DOS65 defaults to verify-after-write OFF.  This
               command works with 1581 drive, too.

*   Negative  coordinates  are  now allowed for all graphics commands.
    Some  commands  require  their  arguments to be "onscreen" such as
    PAINT.

*   BASIC errors now force text mode,  and  TYPE, LIST, DISK, KEYLOAD,
    LOADIFF now catch all DOS errors. Autoboot filename=AUTOBOOT.C64DX.*

*   Opening  an  RS-232  channel,  command  string  allows setting new
    features:

        1      baud (0-16, where 16=MIDI rate)
        2      word len
        3      parity
        4      stop bits (not used)
        5      duplex
        6      xline
        7      xon char (0=incoming flow control disabled)
        8      xoff char (0=outgoing flow control disabled)
        9,10   input buffer pointer (page lo, hi)
        11,12  output buffer pointer (page lo, hi)
        13     high water mark (point at which xoff is xmitted)
        14      low water mark (point at which xon is xmitted)

For  debug  purposes,  the border color will change if an RS232 buffer
overflow  occurs.  To  differentiate  between  a  GET# of a null and a
'no data' null, test bit 3 of STatus (same as C64).

*   Support for latest DOS controller chip,  F011D, includes error LED
    blink  (border  color  still  changes  too,  for now).  Changes to
    improve  FASTLOAD  speed  and  improve SAVE speed.  Will work with
    F011C chip,  but error LED does not blink. Requires latest 'ELMER'
    PAL  for  disk  LED  to work correctly for either controller Chip.
    External  drive  LED  will not work correctly until new PCB & F016
    chip  are  designed.  New  DOS  functions  include  COPY D0 TO D1,
    ability  to  change  sector  skews for files (U0>S#) and directory
    (U0>D#),  and  directory  compress  (i.e.,  empty trash)  via  "E"
    command. Physical interleave is now 7.

*   The  DOS  COPY/CONCAT  bugs  have been fixed,  and COPY now allows
    forms such as COPY D0,"*.SRC" TO D1,"*" and COPY D0,"*=SEQ" TO D1,
    "*". Directory/partition paths not yet implemented, but will be.

The  following  changes/updates/fixes  have been made to the C64DX ROM
code  since the March 1,  1991 C64DX System Specification was printed.
Please make note of them. Current ROM as of this update is 910501.

CHAR       Now  works  to  spec.  and  supports the following imbedded
           control  characters  (although some are buggy;  others  are
           planned):

           ^F       6      flip
           ^I       9      invert
           ^O      15      overwrite
           ^R      18      reverse field on
                  146      reverse field off
           ^U      21      underline
           ^Y      25      tilt
           ^Z      26      mirror

           When  specifying  a  character  set  from  ROM,  note  that
           national  versions  of  the  C64DX  will  have the national
           character  set  at  $39000  and  the  C64  character set at
           $3DC00.  In  US/English  systems,  the  default  C64DX-mode
           character set will be at $39000.

CLR ERR$   Clears BASIC error stuff, useful after a TRAP.

CURSOR [<ON/OFF>,] [column] [,row] [,style]
        where: column,row = x,y logical screen position
               style      = flashing (0) or solid (1)
               ON, OFF    = to turn the cursor on or off

LINE x0, y0 [, [x1] [,y1]] ...
        where: (x1,y1)=(x0,y0) if not specified, drawing a dot.
               Additional coordinates (x2,y2), etc. draw a line
               from the previous point.

LOADIFF "file" [,U#,D#]
         Loads  an IFF picture from disk.  Requires a suitable graphic
         screen to be already opened (this may change).  The file must
         contain std IFF data in PRG file type. IFF pics can be ported
         directly from Amiga (eg., using XMODEM).  Returns  'File Data
         Error' if it finds data it does not like.

MOD (number, modulus)
         New function.

MOUSE ON [,[port] [,[sprite] [,[hotspot] [,X/Yposition] ]]]
MOUSE OFF
  where: port     = (1...3) for joyport 1, 2, or either (both)
         sprite   = (0...7) sprite pointer
         hotspot  = x, y offset in sprite, default 0,0
         position = normal, relative, or angular coordinates
         Defaults to sprite 0, port 2, last hotspot (0,0), and
         position. Kernel doesn't let hotspot leave the screen.


