Manual for Alasm 5.07, translation to English: Alone Coder

▄███████ █████5.07▄███████ ▄█████▀▀ ███████▄

█████▀██ █████▄▄▄ █████▀██ ▄▄█████▀ ██ ██▀██

 

 1. MEMORY

ALASM can work with a number of source texts at the same time.

Each text lies in its own memory page. You can select one text or

another to edit using PAGE [page] or ssENTER (from the list).

Pages are enumerated as in upper memory driver, using its memory mask.

Lower 3 bits of page number are always the same as bits 0-2 of port #7FFD.

When ALASM is loaded it tests memory by all 8 bits of page number.

It results in screen as XXXX kB mask XX that means ALASM founded

XXXX kB of memory and bits in XX are working for changing page.

These bits are used to mask pages in PAGE etc.

Stack address must not exceed #6dff!

ALASM resides in #8000-#bfff. When you compile to #8000-#bfff

it is compiled to system page. When you run your program

or quit ALASM or use the debugger, #8000-#bfff is switched with system page,

so your program sets in its place.

ALASM uses lower memory for IMPORT, EXPORT,

and MOVE. Compilation uses stack extensively.

 

 2. ALASM COMMANDS

Commands can be interrupted by pressing BREAK.

If a command can lose a changed text, it will ask for its saving.

 

 Quit [address][,page]

Quits ALASM. If no parameters given, then exits through RET,

else JP to "address" in "page".

 

 Debug

Jumps to STS7.0. (#db06, page given in setup)

 

 Run [address][,page]

Runs the program. By default the "address"=last ORG address,

"page"=0.

 

 Work [drv:][filename[.ext]]

Loads the file into current page. Extension is "H" by default.

"filename" can contain wildcards (see Catalogue). In this case the last file

fitting will be loaded. If "filename" is not given, the user

will select the file from list.

 

 Catalogue [drv:][mask]

Shows disk catalogue. By default, mask="*.*" (all files).

Mask format: "?" may mean any symbol, "*" means that all the next symbols

may be of any kind. Delimiter ("." or end of line) suggests that all the

further symbols are spaces.

"CATALOGUE C" is a mean to show disk parameters not showing files.

 

 Name [newfilename[.ext]]

Changes the name of the current source text.

 

 Edit [drv:][filename]

Edits text in current page. If filename is given, then file with this

name is loaded into the current page. If it is absent on the disk,

it is created in memory.

 

 merGe [drv:]<filename>

Adds given source text to the end of current source text.

 

 counT <expression>

Evaluates the arithmetical expression.

 

 sYmbol [mask|=number_expression]

Shows list of labels by mask or by value. Works only after assembly.

<number> - label value

NoDef - label was not assigned but was used

Macro - label is a macro name

Wrong - label is undefined due to compilation errors.

 

 Assemble

Assembles (compiles) current source text.

 

 Save [+|!][drv:]

Saves current source text to disk. If "+" is added then all the changed texts will be saved.

If "!" then all the texts in the memory will be saved.

 

 Move

Executes TR-DOS MOVE.

Uses memory lower than #7400.

 

 Info

Shows version number, list of system pages, and list of files (texts) in the memory.

Changed texts are marked with '+'. Files with compilation errors have error count,

others have first line shown.

 

 Page [page]

The page given becomes current.

 

 driVe <drv>

The drive given becomes current.

 

 Jumb [+]

If no parameter it scans the current text to change

directives "-" to "+" (this operation is also executed in every source text loading).

If "+" is added then scans all the texts in the memory.

 

 ssENTER

Also named ALTER. Allows to select file in memory by means of cursor keys.

 

 Ban [+]

Removes current text (or all the texts in the memory if "+").

 

The following commands use overlay:

 conFig

Setup. Can be saved into ALASM body on the disk.

 

 impOrt [drv:][mask]

Converts plain text files into ALASM format.

Mask is filename mask to select a file from.

Asks for uppercasing of lowercase token words (leaves them untokenized if no).

Asks for line breaking by ":", as ALASM allows only one command per line.

If text exceeds page then also asks for next page number.

 

 eXport [+][drv:]

Converts current source (or all if "+") to plain text and saves to disk.

Plain text is CR, not CR+LF.

 

 3. EDITOR COMMANDS

Editor has most of screen for editing and lower line for status

where current page and filename are shown, and also free space

in this page and the size of marked/deleted lines buffer (pocket),

as well as text size and edit mode (Ins/Ovr).

 

Editor commands list (Extend key that is Caps Shift+Symbol Shift):

 Quit - quit to main ALASM shell.

 Assemble, counT - as in main ALASM shell.

 Begin, End - go to begin and end of text.

 Search [searchstring]

Searches from position directly after cursor and until the end of text.

Search can be repeated by ssI, which will start from current position

or from the beginning if cursor is at the end.

If searchstring is not given then old searchstring will be used.

 sYmbol [labelname]

Searches for label defined (that is in the very beginning of line).

labelname can contain few first symbols of the label - all labels starting with this

will be found.

 Xreplace string1<press Enter>string2

Finds and replaces string1 to string2.

Asks for replace: Y - yes, N - no and find further, G - yes and yes further, BREAK - stop.

 coDe XXX>[symbol_code]

Inserts symbol with code given. XXX shows symbol code under cursor.

 Restore

Inserts pocket data (marked and deleted lines) after cursor.

Resets pocket add flag, so the next pocket operation will clear the pocket.

 Clear

Clears pocket.

 Ins/ovr

Changes edit mode: insert to overwrite or back. State can be saved via config.

 Undo

Undoes changes in current line (if cursor was not yet moved from it).

Revertible by means of itself.

 Labels

Shows all labels having no further text in their lines.

They are generally procedure names.

User can navigate between them with cursor keys and Enter,

or can BREAK.

 

Edit mode keys:

ssI - continue search

ssQ (Home on PC keyboard) - moves cursor to the 0th column

ssE (End on PC keyboard) - moves cursor to the end of line

ssSpace - delete current line. It is added to the pocket

ssW (Ins on PC keyboard) - "marks" line that means it is added to the pocket

 If the pocket adding flag is off (after Restore) the pocket is emptied before the operation

csSP - tabulation or Rus/Lat (can be switched in config)

cs1 - Rus/Lat or tabulation

cs2 - inserts space under cursor (always insert, never overwrite)

ssENTER - the same ALTER as in main ALASM shell

cs8 (right arrow) - remembers symbols of previous command

 

Insert mode:

 Symbol is entered moving the rest of the word right.

Word is a part of line having no more that one space in a row.

For example, if you enter a label in a line containing mnemonic, the latter will not move.

 Left arrow - cursor moves to first nonspace to the left.

 Right arrow - cursor moves to first nonspace to the right or the

next tabulation position if no symbols further.

All modes:

 Еnter breaks line apart. If no symbols to the right,

then Enter will go to 8th position where mnemonics are usually entered.

If there are symbols to the right and the cursor is in 8th position then tabulation

is kept after Enter. This is to move labels from commands.

 cs9 (Del on PC keyboard) deletes symbol under cursor. If no symbols further then

joins the next line (in case if the result is no more than 64 symbols)

 cs0 (BackSpace on PC keyboard) if pressed at the beginning of the line -

joins it to the previous one.

 

 4. ASSEMBLER DIRECTIVES

        ORG address[,page]

Sets compilation address (regarding DISP shift). By default page is page

mentioned in another ORG before. In the beginning of assembly it is 0.

 

label   EQU value

Defines label as value. Value may be an expression which is evaluated.

See label=value to re-define existing label.

 

        DISP address

Sets program work address which may be not the same as that where it is compiled.

 

        ENT

Sets program work address to current compilation address.

Example:

SCREEN  EQU #4000

        ORG #8000

        LD HL,BEGIN             ;Source: routine

        LD DE,SCREEN            ;Destination: screen area

        LD BC,END-BEGIN         ;Size: routine size

        LDIR                    ;copy

        CALL SCREEN             ;call it

        DI

        HALT                    ;hang forever

BEGIN  DISP SCREEN

MARKA   DEC A

        HALT

        JP NZ,MARKA             ;we use JP and it works

        RET

       ENT

END

 

You can get current DISP shift (shift=org-disp) this way:

a       ORG 0

        ENT

shift   ORG a+shift

        DISP a

 

        INCLUDE "drv:filename"[,page]

Compiles another source by the way. "filename" is its name on the disk.

The name may contain wildcards, and the last fitting file on the disk will load.

"" is any file.

If it is already in the "page" under this name then it will not load.

If "page" is not given then it will load into the current page, overwriting

the current source, so it will re-load after included source finishes.

The current source will continue from the next line.

Example:

        LDIR

        INCLUDE "TOKENIZE",1

        OTDR

        INCLUDE "ALASM2"

        HALT

LDIR will be assembled, then some "TOKENIZE.H" source which will be loaded

into page 1, then OTDR, then some "ALASM2.H" source which will be

loaded atop of current source, then the current source will re-load

from the disk (don't forget to save it before) and continue from HALT.

 

        MAIN "filename"[,page]

Compiles given main source instead of current one

(which is considered a minor unit in the project).

Must be the first command in the source.

Symbols "." and "*" in the filename must be given as "?".

Example:

        MAIN "MAKE6?7",6

        LDIR

When ASSEMBLE is executed the compilation will start

from MAKE6*7 source residing in page 6,

which is supposed to INCLUDE this minor unit containing

MAIN and LDIR. When INCLUDEd the MAIN directive will be ignored,

and the compilation will continue from LDIR.

 

        INCBIN "drv:filename"[,size]

Includes into compiled code a code block of size bytes

(or with size specified in the directory) loaded from disk.

If the file on disk is longer than size it will be loaded partially.

 

        DUP <number>

Beginning of block which is repeated number of times during compilation.

Number may be expression as always.

 

        EDUP

The end of this block.

DUP may be inside another DUP.

Example:

        DUP 32

        LDI

        LD A,B

        OR C

        JR Z,$+3

        LD (HL),D

        EDUP

This block will compile 32 times.

Can use counters made of labels (see label=value) and have

conditional compilation branches.

 

        REPEAT

        <body>

        UNTIL0 <expression>

Repeats <body> until <expression> will be 0.

 

        DB byte|string[,byte|string...]

The same as DEFB. Bytes may be expressions (lower byte of the result is used).

Example:

        DB "A",13,10,"big",13,5+5,"brown",13,10,"fox",13,10

        DEFB "jumps over",13,10,"the lazy dog",EOFsymbol

 

        DW word[,word...]

The same as DEFW.

Example:

        DW ALASKA,BUFFER,12,#BD15,32767,.NUMB1

        DEFW 12345,34567

 

        DS howmanytimes[,bytes]

The same as DEFS.

Bytes (by default the zero byte) are inserted into the current

compilation address so many times as specified.

Example:

        DS 10,#E5

        DEFS 32,#ED,#B0

 

        DD [#]hexbyte[hexbytes]

Compiles hexadecimal bytes.

        DD 1D4FDC,4223

is the same as

        DB #1D,#4F,#DC,#42,#23

 

        +<something>

DON'T USE WITH LINE SIZE=#2C..#2F!

After a text is loaded from disk it is scanned for "+" in the beginning of lines

("-" becomes "+").

Compilation will compile these lines and change "+" to "-" so they will not compile

the second time.

Example:

        LD HL,#DB00

         +SAVEADR

         +  ORG #DB00,7

+           INCBIN "sts70r"

+       ORG SAVEADR

        JP (HL)

STS will load only at the first assembly.

 

label=expression

Define or re-define the label.

Example:

SHLUSS=0

        ORG 32768

        DUP #4000

        DEFW SHLUSS

SHLUSS=SHLUSS+1

        EDUP

Memory after #8000 will be filled with words 0..16384.

 

        IF0 <expression>

        <body1>

        [ELSE

        <body2>]

        ENDIF

If <expression>=0, the <body1> is compiled, else <body2>.

 

        IFN <expression>

        <body2>

        [ELSE

        <body1>]

        ENDIF

The opposite.

Conditional compilation inside conditional compilation is possible,

up to 254 layers.

 

        LOCAL

        <body>

        ENDL

Local label block. All labels inside this construction

will be invisible outside (except for labels starting from @

which are global labels). LOCAL inside LOCAL is allowed.

If a label is defined inside LOCAL block but this label

was accessed outside, it will be global:

        LD HL,LABEL

        LOCAL

LABEL

        ENDL

 

        MACRO <macro_name>

        <body>

        ENDM

Macro definition.

Inside macro:

\0..\9 - parameter 0,1,2,..9

\C - current symbol in parameters

\N - go to next symbol in parameters (returns nothing)

\S<char> - string from current symbol until <char> symbol

\P - shift parameter numeration. parameter 1 becomes 0 etc. Parameter 0

is returned.

\R - restores initial parameters enumeration as it was before \P.

 

        <macro_name> [parameter1[,parameter...]]

Use macro.

Parameters are divided by commas (not counting commas in quotes).

        MACRO DOWN

        LOCAL

        INC \C

        LD A,\C

        AND 7

        JR NZ,LABEL

        LD A,\N\C

        SUB #E0

        LD \C,A

        SBC A,A

        AND -8

        ADD A,\R\C

        LD \C,A

LABEL

        ENDL

        ENDM

This is generic DOWN HL or DOWN DE routine that counts screen address

a line lower that current one.

Using conditions of this type:

        IF0 "  "-"\1  "

or:

        IF0 ?macroname\1-2

we can use macros with floating number of parameters (see \P to shift them).

 

        DISPLAY [/L,]["any text",][[/D|/H|/A,][/T,]expression]

Displays messages and/or numbers while assembly. /D, /H, and /A keys define

output format for one next number. Numbers without keys are shown in

current system (see config). /D - decimal number, /H - hexadecimal, /A - both systems.

/L defines displaying in old line, without line leed and carriage return.

/T shows the expression given, then its value.

Examples:

        DISPLAY "code size: ",/D,end-start

        DISPLAY /A,"abc+xyz=",abc+xyz

        DISPLAY "simple"," text"

 

        DISPLAY "This is one "

        DISPLAY /L,"message"

 

        DISPLAY /A,/T,abc+xyz

is the same as

        DISPLAY /A,"abc+xyz",abc+xyz

 

        RUN address[,page]

Calls the specified routine while assembly.

All the Post-labels are not evaluated yet, ALASM is in #8000.

 

IX and IY halves: HX,HY,LX,LY.

This is also possible:

INF

SLI

OUT (C),0

EXA

EXD

JZ

JNZ

JC

JNC

LD L,0,H,'fnt

 

 5. Expressions

Evaluated left to right without priorities (except for brackets).

16-bit signed/unsigned integers are used.

a+b

a-b

a*b

a/b

a&b - AND

a|b - OR

a!b - XOR

a>b - cyclic shift of word "a" "b" bits right

a<b - ...left

() - brackets (they are evaluated first)

{a} - word in memory address "a"

a~ - invert current result (-1-a)

?label - returns 0 if label is defined, #ffff if not defined,

    1 if not defined but accessed before, 2 if label is macro.

'a - higher byte of a

.a - lower byte of a

%const - binary number

$ - current compilation address (shifted if inside DISP)

$$ - current compilation page

All operations except + and - don't allow labels not defined before

due to one-pass compilation method.

 

How to detect (not from macro) the current source page being compiled

and the current line address:

        ORG #C0E1,2

        DISPLAY {$}-#C040,"/pg",.{$+2}

 

How to detect if we are compiling under mkace:

        ORG #FF32,2

        IF0 {4>4+{$}}-#BF43

make           ;mkace!

        ENDIF

 

 6. ERRORS

0 syntax error

3 JR out of range

6 double definition of a label

10 compilation into ROM

11 wrong operation

12 wrong MACRO operation

14 system stack error

15 disk error

Errors after assembly:

wrong short - wrong short displacement

not defined - label not defined

 

 7. CONFIG

 Load FONT codes

Loads font "FONT*" #9c40,#400(#8045,#3f0).

 Start page

Page which will be current when ALASM starts.

 System page

Where ALASM resides when inactive.

 Symbol list

Pages containing labels while assembly and usable after it.

If you don't need 4 pages for labels, then zero unused ones from the left.

The first page used is the rightmost one.

Label pages are filled from their ends.

 Post symbols

Pages containing post labels while assembly and unusable after it.

Contains data to evaluate labels used prior to define.

The first page used is the rightmost one.

Post label pages are filled from their starts.

 Pocket page

Page containing copy buffer (pocket). Assembly clears it.

May be the same as Post.

 HImem driver

Sets a driver of higher memory (#7000,#FF)

 

Files:

alasm64 .B - ALASM 64 pitch loader

alasm_64.C - ALASM

olasm_64.C - overlay

FONT64a .C

FONT64b .C - font by Faster FIXED

 

alasm42 .B - ALASM 42 pitch loader

alasm_42.C

olasm_42.C

FONT42a .C

FONT42b .C - bold font

 

sts70r  .C - debugger

 

gruzilka.B - loader from drive B

 

128КDRV .C - 128k memory driver

PENTDRV .C - Pentagon 512k memory driver

P1MBDRV .C - Pentagon 1M memory driver

P4MBDRV .C - Pentagon 4M, or 2M without extra wiring (uses #FD and #AFF7)

ATMDRV  .C - ATM 1M memory driver

PROFDRV .C - PROFI 1M memory driver

ZSKAY512.C - SCORP/KAY memory driver (uses 512k on KAY)

KAY1DRV .C - KAY 1M memory driver

SCORP1M .C - SCORP 1M memory driver

 

al50stri.H - ALASM format description

Fnt42Bld.H - 6x7 (6x6) font converter from screen to #3f0 ALASM font format

REFNT42 .H - does the opposite

 

H_Search.B - searches ALASM sources in ruined disk

H_Search.W

 

Marazm.H, Humor.H, Humor.C

Examples of using RANDOM macro that returns pseudo-random number in given range.

SNAKE.H

The game that plays while ASSEMBLEing it. Credits to RST7 that created this for TASM.

BUILD+.H

Counts builds of your project and allows to insert this number into

your release, as well as edit session number and build date.

SAVEOBJ4.H

Saves code blocks with any extensions from given addresses with given sizes.

Is used with RUN[CS/Enter]. See information inside.

No more saving via debugger!

SAVEBAS/.H

Allows to create a basic file containing your code inside.

 

INCOMPATIBILITIES WITH v4.44:

ORG without page number does not set page 0.

Macro parameters are with \, not :

DB """,0 now means DB """,0". Write DB 34,0 or DB """",0