This manual is setup using the LW_Roma font. If you do not have this font, you can find it on quantumlink.
geoCOPE is being distributed as a user-supported software package. Registration fee is $15.00. For a copy on disk of all the files uploaded to quantumlink in this set, send an additional $5.00 ($20.00 total).
geoCOPE is (c)copyrighted 1988 by
Bill Sharp Computing
P.O. Box 7533
Waco, TX 76714
geoCOPE
User's Manual
Version 1.3
Copyright (C) 1988
By
Bill Sharp Computing
All Rights Reserved
Bill Sharp Computing
P.O. Box 7533
Waco, TX 76714
(817)776-2958
Q-Link: Bill BSC
Table of Contents
Section 1: Using the Editor
Typing for the assembler 1
Inserting text 1
Deleting 1
Menu Selections:
File Menu
Load 1
Save 1
Print 1
Quit 1
Save as... 1
Edit Menu
Cut 2
Copy 2
Paste 2
Clear 2
Search Menu
Find 2
Replace 2
GoTo... 2
Clear 2
ToolBox Menu
AutoSave 3
BookMark 3
Using TextScrap 3
Section 2: Coding for COPE
Requirements 4
Instruction format 4
Mnemonics 4
Labels 4
Constants 5
Pseudo Operators 6
Arithmetic Operations 10
Hierarchy of equations 10
Section 3: Using the Assembler
Startup 11
Quit Icon 11
Screen Icon 11
Start Icon 11
Size and Position 11
Filename 11
Error indicator 11
Pass Indicator 11
Pause Icon 11
Savefile DB 11
FileSize 11
LabelArray Size 11
Error Messages 12-13
Section 1: Using the Editor
page 1
Section 1: Using the Editor
page 1
Typing for the Assembler
Since the assembler requires each line to hold only one mnemonic, word wrap is not supported. Each line is considered to have a carrage return at it's end. Therefore pressing the RETURN key does not insert a carriage return, it takes you to the next line. If you wish to split a line, hold down the C= (commodore) key and then press the RETURN key. This will split the line.
@Simple Inserting
To insert a single space use the insert key. Press the INST key while holding down the shift key.
@Simple Deleting
To delete the character you've just.typed, press the DEL key. To 'suck' in characters from the right, press the BackSpace (
) key. . The character will be deleted. This is how you can join together two separate lines. Go to the end of the line and press the BackSpace key. The next line will be append to the present one. The DEL key will also delete the currently active range, if their is one.
@Menu Selections
Now lets cover the menu selections.
Under the Commodore logo menu will be the information and deskAccessories selections. If you have no deskAccessories on the current disk then only the information menu is available.
@FILE
@Load
: This is the menu selection to load a file. If you haven't created a file yet then this will be blank. The load routine first checks to see if the current file had been saved. If the AutoSave function is on, the file will be updated automatically. If not, then you are asked if you would like to save the file.
@Save
: This will save your current file. Everytime a file is saved copeEditor saves the current file status to ensure you don't quit with a changed file. This takes a few seconds depending on file size.
@Print:
This loads the print driver current on the disk and prints the file in ASCII, not graphics mode. Of course, if their is no print driver on the disk or the printer is turned off this routine will not work. Print uses the first print driver found on the disk.
@Quit
: Exit this program and return to the deskTop. First the file is checked for any new changes and you are allowed to save the file if it has been changed.
@Save As..
.: Allows you to change the name before the file is saved. You can select it if you wish this file to be a Seq. file or a VLIR file. VLIR files allow multiple 'pages' to be kept under the same name. Also can be used to append the currently loaded document to the first blank page of a VLIR file. Select "Save As" and enter in the filename you wish to append to.
page 2
@EDIT
The edit menu allows you to work with characters, wo
page 2
@EDIT
The edit menu allows you to work with characters, words, and lines all at one time. The editing functions are performed on ranges that you selected. You can select ranges with the mouse or from the keyboard using the RUN/STOP key. Pressing RUN (do not press shift)will start the range selection process. Pressing RUN again marks the end of the range. Notice, the reminder 'EX' at the bottom of the screen to show that range extension is on.
When selecting a range with the RUN key, all the movement keys are active in selecting the range. See the Keyboard shortcuts list for these keys.
: This selection removes the selected text from the text file and places it on the disk as a Text Scrap file.
@Copy
: This selection does not remove the selected text, it copies it to the TextScrap file.
@Paste
: Paste does not work with ranges, it takes the current Text Scrap file and inserts it at the location pointed to by the TextPrompt.
@Clear
: This is an absolute erase. It delete text from the file but does NOT save the text to the TextScrap.
@SEARCH
One of the most useful time-savers of any text editor is the ability to search through an entire document and pick out each occurrence of a word, code or label than needs to be changed. The Search menu gives you two options: Find, and Replace.
@Find
: Goes through and finds up to 32 characters of text. You have the options of starting at the top of the document or from the current cursor position. You can match the Case of the phrase exactly or ignore capatalization.
Each time the search process locates the word or text you entered, it stop and displays that line at the top of the screen. To continue the search, click the FINDNEXT button at the top of the screen. Keep clicking the FINDNEXT button until you see an dialogBox that announces, Search Complete.
@Replace:
When you want to change or replace a word the command to use is Replace. Just as with Find, you start by entering the text you want to find and the text you want to replace it with. You have the same options as starting at the top of the document and matching the Case of the Find text. You can also select if you want to be prompted for each change. If you do, you can select a YES,NO, or CANCEL during the Replace function.
@GOTO
: GoTo allows moving quickly to a new page within a VLIR file.
page 3
@TOOLBOX
AutoSave:
geoCOPE gives you t
page 3
@TOOLBOX
AutoSave:
geoCOPE gives you the option of having it automatically save your files for you or allowing you to make that choice yourself. Change the option here. Please note, this option is stored with the file. The current status of AutoSave for each file may be different.
@BookMark:
BookMark gives you the capability or returning to the last place you left the file your editing. If BookMark is on, then you can return to the same location your currently at. If BookMark is off, you start at the beginning of the file. BookMark is updated everytime you save the file. This option is also stored with the file.
@Using the Text Scrap file
The TextScrap file keeps all your most recently edited text scrap. If you start using the text manager desk accessory, you can accumulate frequently used routines and insert then into your new program as you need them. The GEOS user's guide explains the use of the text manager in more detail.
Section 2: Coding for COPE
page 4
This section will show you the various formats and commands you can use within geoCOPE
@Requirements:
Programming in Assembly Language requires learning the inst
Section 2: Coding for COPE
page 4
This section will show you the various formats and commands you can use within geoCOPE
@Requirements:
Programming in Assembly Language requires learning the instruction set (opcodes) of the computer, using the Assembler to create the program, and the specific requirements of the operating system. If you haven't done so, I suggest purchasing 'The Offical GEOS Programming Reference Guide' from your local bookstore.
@Instruction formats:
A line of Assembly Language code looks like this:
(label) opcode (operand) (comments)
The fields that are bracketed are considered optional depending on the opcode used.
@Mnemonics:
Each machine instruction has a symbol name referred to as an operation code(opcode), also called a mnemonic. Their are 56 such mnemonics in the 6510 instruction set. A typical mnemonic look like this:
RTS
Note that this mnemonic does not have a label or use a operand.
geoCOPE is not case sensitive about mnemonics. Use can use upper or lowercase letters in describing the mnemonics. RTS, rts, Rts are all considered the same.
Some Assemblers have a special operand for certain mnemonics. For example: The MADS assembler uses the letter A as a operand for the following four instructins: ASL, LSR, ROL, and ROR. copeAsm does not require this.
@Labels:
Their are two main types of labels, reference to a memory address and numeric labels. A reference label is placed next to certain code that you might want to call, where a numeric label is normally assigned a value.
Label1 LDA #1 ; this is a address label
Label2 = 50 ; this is a numeric label.
Their are a few special notes to remember about labels.
1. Labels are Case sensitive. The words 'Label' and 'label' are not the same to the Assembler.
2. Labels must start with an ASCII character, they cannot start with a number. They can have a number included within the label itself such as 'Move2there'. Labels are limited to 32 characters.
3. Do not accidently include any math operators. (see Arithmetic Operations)
4. All numeric labels with the value of less that 256 ($FF) must be assigned their value before their used. This can normally be done in a 'equates' file.
Page 5
Labels with a value of less than 256 have to be declared before use for the following reason. The Assembler is a two pass Assembler. Memory is divided up into ZeroPage and Absolute. Ze
Page 5
Labels with a value of less than 256 have to be declared before use for the following reason. The Assembler is a two pass Assembler. Memory is divided up into ZeroPage and Absolute. ZeroPage is treated differently by the assembler and processor for optimization of program code. Many instructions have a different meaning when the operand is a ZeroPage
value. If you reference a label before it's declared then it is assumed to be a Absolute label and you program code will be wrong and possibly not work.
@Local or Branch labels
Branch labels consist of a commercial-at-sign (@) followed by a sequence of characters. The branch label allows alphanumeric characters and have unlimited length. Only the first four characters will be used to define the label. It is called a branch label because of the way it is used. You can only use a branch label as the destination of a branch instruction. A branch label is not added to the label as other labels are.
A branch label can only be used within the same file. You cannot use a branch label that jumps across a "INCLUDE" directive.
Example:
CodeHere
LDA #$40
STA $4000
LDA StatusFlag
BNE @StatusOn
BEQ @0001
@StatusOn
; notice that only the first four characters will be 'seen' by the assembler. They are
; 'Stat'.
@0001
; '0001' is different that '001' and '01'. the label is read as a character string.
You can have up to 32 branch labels outstanding. A outstanding branch label is where you branch forward in the file to a spot lower in the file. The above examples are forward branches.
@Constants:
You can use constants from the following number systems; binary, hexadecimal, decimal. Decimal is the default number system and a prefix character can be used to declare the others.
$ (dollar sign) Hexadecimal
% (Percent sign) Binary
' (Apostrophe) ASCII literal character
" (Quote) ASCII literal character
LDA $4000 ;load accumulator from address $4000 (16384)
LDA #%00100011 ; load accumulator from the binary representation of 35.
LDA #"G ; load the ASCII value of the character G into the accumulator
Binary Constants: These are the numbers 0-1.
Decimal Constants: These are the numbers 0-9
Hexadecimal Constants: These are the numbers 0-9 and the characters A-F.
page 6
@Pseudo Operators:
Their are twenty one dir
page 6
@Pseudo Operators:
Their are twenty one directives that you can use to give the assembler special instructions. This is where copeAsm will differ most with other assemblers so let's cover them in detail.
[EQUALS]
The equal sign is used to assign a value to a label. It cannot
be used to reserve memory locations or reset the program counter. It is used to create numeric labels.
Label = 500
Label = 4*5+2-TWO
The following pseudo-ops require a period before the command word. The first letter of these pseudo-ops should be a
@UPPERCASE letter!
If desired, all pseudo-ops which are preceded by the period may be abbreviated. The abbreviation follows the full word in the examples below.
@ .BYTE
[Byt]
Is used to reserved one byte of memory. Multiple operands may be used if separated by a comma. ASCII text strings can be generated by enclosing them in quotes. (Single or double quotes).
Tables .Byte 5 , 5 , 5
.Byte 128+2
.Byte 'This string includes the double quote (") within it '
.Byte "This string includes the single quote (') within it "
Note that the strings use the opposite quote to contain the quote character needed for the string.
.Byte 5000 ; this outputs only the lower byte (136)
@ .WORD
[Wor]
Is used to output two bytes of data at a time. Addressed are stored in low-byte, high-byte order.
Tables .Word $4F00
This would be stored with 00 bytes first followed by $4F.
The most common use for Word is to generate address with a label, such as.
.Word MenuText
@ .PC
[PC]
PC is short for Program Counter. It can be used in a similar fashion as an Asterisk in some Assemblers. It is generally used to change the program counter to a new value.
LabelHere
.PC = LabelHere + 25
In the above example, the PC command will take the Program counter, and add 25 + the value of LabelHere to it.
Since the Pc command changes the Program counter, make only small changes to its value.
page 7
@ .INCLUDE
[Inc]
Include is used to include the source code from other files into the assembly process. When the assembler incounters this directive, it marks
page 7
@ .INCLUDE
[Inc]
Include is used to include the source code from other files into the assembly process. When the assembler incounters this directive, it marks the current file and loads the new file and starts assembling the source code there. When it's through with that file, it reloads the original file and resumes with it. You would normally place Include statements at the beginning of your source file to include suce things as ZeroPageEquates, Constants, and Library files. Do not enclose filenames with quotes. Place a CarriageReturn immediately after the filename. This prevents you from accidentally including spaces with the filename. Include will automatically search both drives in a two drive system.
.Include Equates
.Include Routines
The filename given can be a Seq. file or a VLIR file. If a VLIR filename is given, the entire VLIR file is included. If you wish to only include one 'page' from a VLIR file, then follow the name with a comma and the record number of the page.
@WARNING
! The record number is always one LESS that the page number.
.Include TestFile,1; includes the 2nd page of TestFile.
6: .
@START
@Start
describes to the assembler where in memory the program will start at. This is the value stored in the File Header for this file and is the load address for the file. This directive should be the first directive for your source file. It is only used once and is optional. If left out, the default starting position is at $0400.
@Start
also updates the Initialization address to the same as the
@Start
address. This can be changed with the Initprog command below.
.START $800
@ .INITPROG
[Ini]
@Initprog
can be used to change the initialization address that is normally the same as the start address. If you store data as the front of your file this can come in handy. It has several methods of use.
DATA
DATA
DATA
.Initprog ; use by it self it will take the current Program counter value.
or...
.Initprog Initroutine ; use it with a label pointing to the initialization routines
DATA
DATA
Initroutine
or...
LDA #0
.Initprog $600 ; or use it with a direct value.
@ .AUTHOR
[Aut]
Allows setting the Authors name in the fileheader. Do not use quotes. Place a CarriageReturn immediately after the filename. This prevents you from accidentally including spaces with the filename.
.Author Bill Sharp BSC
page 8
@ .NAME
[Nam]
Allows setting the permanent name in the fileheader. Do not use quotes. Place a CarriageReturn immediately after the filename. This prevents you from accidentally including spaces with the filename.
.Name COPE Source V1.0
.Name "COPE Source V1.0",0,0,0,0 ; use this form to pad out all twenty bytes. This is useful if you need to set the 40/80 column flag for GEOS128.
10:
@.TYPE
[Typ]
Allows setting the file type for this file, the default is a APPLICATION file
.Type 6
11.
@ .Icon
[Ico]
ICON is used to define the Icon for this file. This requires 63 bytes of data to described the Icon. This data is not stored in the final program.
The block command is the most convient way of reserving a range in memory. The command syntax follows:
.Block Length [,Value]
Length is the number of bytes to output, Value (which is optional, zero is the default) is the byte value to use. Block can be used in the following ways.
.Block 20,0 ;outputs 20 zeros
.Block 10,5 ; outputs 10 fives
.Block 20 ; outputs 20 zeros
.Block 20,'A ; outputs 20 "A's" (value 65)
13:
@ .HEX
[Hex]
Change screen listing to hexadecimal
14:
@ .DEC
[Dec]
Change screen listing to decimal format
15:
@ .SON
[Son] short for ScreenON
Turns the screen listing feature on.
@ .SOFF
[Sof] short for ScreenOFF
Turns the screen listing feature off.
page 9
17.
@.DNAME
[Dnam]
Dname is short for diskname. This is the actual name that is shown from the
page 9
17.
@.DNAME
[Dnam]
Dname is short for diskname. This is the actual name that is shown from the DeskTop. This command is optional. If you use a name that is found on the disk you are asked if you wish to replace it.
18.
@.NEWPC
[Newpc]
Newpc allows changing the actual assembly address without changing the way code is stored in geoCOPE's internal bufffer. This is a convient command for setting up sections of code that is assembled at the same address. This will usually be done when working with VLIR records.
19.
@.SEGMENT
[Seg]
Segment is used to describe the layout of a VLIR file. As the assembly process continues, code is stored in geoCOPE's internal buffer. When a segment command is encountered the internal buffer is stored to the disk. The buffer is cleared and is ready for new code. The record number is optional. For the first segment used, if a record number is not given then the default will be zero. For every segment afterwards that does not have a record number after it, the current record number will be incremented by one.
20.
@.MAC
[Mac]
@.MND
Mac is short for macros. This is where you start defining your macros. MND is short for MacroEnd. The code included between the macros is simply assembly source code.
Parameters can be passed to the macro. When you envoke the macro (by using it's name) include the parameters you wish to send it after the name. Separate the parameters with a colon. The macro can have up to 9 parameters passed to it.
To declare a macro:
.Mac loadw
lda #<?1
sta?2
lda #>?1
sta ?2+1
.MND
To execute the macro:
@ loadw R0:FileName
This macro load the position of the first parameter and stores it in the second parameter.
R0 is now pointing at FileName.
Macros can be nested up to 4 levels. Parameters cannot be passed to a nested macro.
21.
@.DRIVE
[Dri]
.Drive [Drive #]
Drive can be used to change the current drive. When used with no value, it switches drives. You can include a drive number if you wish.
page 10
@Arithmetic Operations
the four basic arithmetic operations and three logic operations are denoted:
* Multiplica
page 10
@Arithmetic Operations
the four basic arithmetic operations and three logic operations are denoted:
* Multiplication
/ Division
+ Addition
- Subtraction
& Logical AND
^ Logical EOR (Exclusive OR) (press the up-arrow key for this symbol).
| Logical OR (press the C= key and the up-arrow key for this symbol).
Currently geoCOPE does not allow parenthesis in it's equations. Parenthesis would be confused when dealing with addressing modes.
@ Hierarchy of arithmetic and logical operations:
Highest
* / Multiplication and Division
+ - Addition and Subtraction
& Logical AND
^ Logical XOR
| Logical OR
Lowest
Any equation using labels, constants, and the above arithmetic operators can be used in place of an operand. Equations can be used in the Pseudo-Ops that expect a math value for a answer.
Lets see some examples:
.Byte 5 , 5 ; typical byte statement.
.Byte 2*14+1 ; this will give 29 as a value.
LDA #25 ; typical load Accumulator statement
LDA #25*4+3 ; loads the accumulator with 103.
Labels can be used also. Be careful using address labels.
LDA #LeftMargin +5 ;If LeftMargin = 20, then this loads 25 into the accumulator.
.Byte MenuBottom+4*14+1 ;This add 57 to MenuBottom.
When describing menus in GEOS, your first byte is
.Byte 128 | 5 a 128 OR'ed with the count of menu Items.
And #%0110010 Logically AND a value with the binary value 50.
page 11
Section 3: Using the Assembler
Using copeAssembler is relative easy. The hard work is coding the programs.
@On Startup
The startup screen only h
page 11
Section 3: Using the Assembler
Using copeAssembler is relative easy. The hard work is coding the programs.
@On Startup
The startup screen only had three Icons active. The Screen listing Icon, The Start icon, and the Quit icon.
@Quit Icon:
The quit icon allows you to get back to the deskTop. If you press this icon during the Assembly process you are asked if you want to quit. If you answer yes then you will return to the DeskTop.
@Screen Icon:
By pressing the
and
switches, you can control the listing of the assembly process to the screen. You can even do this during an assembly. Listing is only active during the second pass.
@Start Icon:
The Start Icon brings up a dialogbox so you can select the file you wish to assembly. Select the file and the assembly process begins.
Once the assembly process is under way, their are several other status indicators and another icon to watch.
@Pos: and Size.
this display the current filesize and the position the assembler is within this file. The position is updated at every ten lines of source code. Printing to the screen during an assembly is time consuming!
@Filename box
: this box shows the current file being assembled.
@Soft and Hard Errors
: A soft error only occurs when their is a pseudo-op that the assembler does not understand. It is up to you to determine if the error is fatal to the program. Hard errors are almost always fatal to the program being assembled. You might want to continue to see if you can find any more errors. At each error the assembler pauses. Pressing the joystick button signals the assembler to continue.
@Pass Indicator:
This shows you which pass your on.
@Pause Icon:
This icon allows you to stop the assembly process to take a look at your code. If you turn the screen function on then the assembler will display to the screen. Sometimes this is too fast to read and you will need to pause the screen. To restart, press the pause icon again.
@saveFile dialogBox
When the assembly process is finished, you are required to give a name to the file before it is saved to the disk . This may be done with the Dname pseudo. geoCOPE also displays some vital statistics about the file it's saving.
@FileSize
: this is the actual size of the file. Currently, this has a maxium of 8K (8,192 bytes). Each record of a VLIR file may be 8K in size. Do not over extend the internal buffer.
@LabelSize:
This is the size of the label array built in memory during the assembly process. This is limited to 5000 bytes currently.
@LabelCount:
This is for your information. Their is no limit on the count of labels.
@copeAssembler Error Messages
page 12
Without error messages, it's hard to figure out what's wrong with your program. Here are the explanations of the error messages.
@Error Messages:
@NOT A VALID COM
@copeAssembler Error Messages
page 12
Without error messages, it's hard to figure out what's wrong with your program. Here are the explanations of the error messages.
@Error Messages:
@NOT A VALID COMMAND
This is the error message you get when copeAssembler does not understand the directive or pseudo-op. All pseudo-ops begin with a period. Check for mispelling of the pseudo-op. Check that the first character is a Capital letter.
@DUPLICATED LABEL
This label has been used twice in your source code. Either you have used it as a numeric label twice or as a address label twice. Or once each.
@NOT A VALID LABEL
The first character of this label is invalid. The first character must be alphabetic.
@UNABLE TO FIND LABEL VALUE
When a label is used in an expression (an operand), The label value could not be found in the label array. Check spelling and syntax of label.
@INCORRECT CHARACTER FOR HEX VALUE
A non hexadecimal character has been found while trying to interept a hexadecimal ($) number. Hexadecimal only allows 0-9,A-F. A-F must be in
@CAPS
@INCORRECT CHARACTER FOR DECIMAL VALUE
A non decimal character has been found while trying to interept a decimal number. Decimal only allows 0-9.
@INCORRECT CHARACTER FOR BINARY VALUE
A non binary character has been found while trying to interept a binary number.
Binary only allows 0-1.
@ADDRESS VALUE NOT ZERO PAGE
The operand value is greater that 255 ($FF). Some opcodes do not allow this depending on the addressing mode. Example: LDA (misc),Y
@misc
cannot be greater that 255.
INCORRECT ADDRESSING MODE
The expression (operand) is invalid for this opcode. Check to make sure you can use this addressing mode. Check the placement of the comma.
INDEX IS NOT A VALID CHARACTER
This message is given when you try to use the X register with the LDX and STX commands.
@INDEX MISSING
@INDEX MISSING AFTER COMMA
page 13
In an indirect addressing mode, could not find a index (X or Y) after the comma.
X INDEX ADDRESSING MODE INCORRECT
In Pre-Indexed indirect addressing, the X index is misplaced or missing.
BRANCH OUT OF RANGE
All of the branch instructions are assembler into two bytes of code. The first byte is the opcode and the other byte is the position relative to the next byte to branch from. A branch forward is limited to 0-127 bytes. A branch backwards is limited to 0-128 bytes. If your branch is out of range, their is too much code between the branch instruction and the destination.
UNABLE TO EVALUATE ADDRESS-MODE
The operand start with a value of less than 36 and cannot be evaluated.
NAKED MNEMONIC
The opcode should have an operand following it. When no operand is found and the opcode expects one, you get this error.
ERROR IN INDIRECT ADDRESSING MODE
The opening parenthesis was found for the operand, but no comma or closing parenthesis could be found. The operand type could not be evaluated.
Y INDEX REGISTER NOT DECLARED
A Post-Indexed Indirect addressing mode is missing the following Y register character.
@INSUFFICIENT DISK SPACE
While trying to save a file, it is found that the disk in the drive does not have enough room to hold the entire file. Change disks with the
@DISK
icon.
@YOU HAVE EXPERIENCED DISK ERROR #
Their is a problem with the disk drive. Check the corresponding number to the disk error numbers below. These numbers correspond to the disk error chart in the 'Programmers Reference Guide'. The most common disk error found will be the 'FILE_NOT_FOUND' error. This will happen when you INCLUDE a file and the file is either missing or the spelling of the filename is wrong.
Disk Error #: Description
1 NOT_ENOUGHT _BLOCKS
2 INVALID_TRACK
3 INSUFFICIENT_SPACE
4 FULL_DIRECTORY
5 FILE_NOT_FOUND
6 BAD_BAM
13 DEVICE_NOT_FOUND
$73 DOS_MISMATCH
All other errors are problems with the disk. Check the disk for sector errors.
(.txt)