From: rossi@opal.cs.tu-berlin.de (Oliver Rosenkranz)
Subject: S.A.M. Part II (Accessory and address)
Content-Type: text/plain
Content-Transfer-Encoding: 8bit
Organization: Techn. University of Berlin, Germany
Mime-Version: 1.0
Date: Sun, 10 Jan 1993 18:01:04 GMT

Hi there !

Last week I posted an article covering the program Screen Aided Management
for the ATARI XL/XE computers.
I have been asked several times where you can get it and some other
things. So I decided to write it down and post it here :

Screen Aided Management (S.A.M.) is powerful software package. It gives the
XL/XEs a desktop with windows/icons pull-down-menues and 80 columns per row
(and many other great features I described before - If you wanna have the
first text send me a mail (rossi@cs.tu-berlin.de).).

S.A.M. is a commercial product. Its basic parts had been published in 1988/89
in the German computer magazine ATARImagazin .
Now it is distributed by a German company. Here is its address :

Power per Post (PPP)
Postfach 1640
7518 Bretten
Germany

You may also get there other products for the 8 bit ATARIs, so be clever
and order a catalog first.

The newest version of S.A.M. is V1.25 and it seems that this is the last
update. The authors of S.A.M. are working on an English version (the software
itself/commands/... are in English but the manual is written in German) of
it which will be distributed in the US. But I can't say when.

Some people wrote me that they want to hear more about how to program
accessories which are compatible to S.A.M. . Okay, here it is. There
may be some lines of my first posting of it but this is for those who
didn't catch it.

S.A.M. has the ability to start accesories to give the progammer a chance to
use all the features S.A.M. is providing.
There are still some accessories out there. They were mentioned and described
in my first posting. I'm actually working on an accessory (a Filelist utility).

Okay here, again, is the memory map of the 800 XL having S.A.M. installed :

$0000-----------------------------------------------
	OS variables and vectors
$0600-----------------------------------------------
	S.A.M. variables
$0700-----------------------------------------------
	DOS
$1F00-----------------------------------------------
	free memory
$2400-----------------------------------------------
	S.A.M.
$2600-----------------------------------------------
	free memory (but is temporary used by S.A.M.)
$3000-----------------------------------------------
	font
$3400-----------------------------------------------
	player graphics
$3800-----------------------------------------------
	S.A.M. vector list
$3900-----------------------------------------------
	S.A.M.
$6010-----------------------------------------------
	Screen
$8000-----------------------------------------------
	S.A.M. utility
$xxxx----(depends on length of utility)-------------
	free memory
$C000-----------------------------------------------
.
.
.
The utility which loads the accessories and controls them uses
the memory from $8000 to $83FF.So, S.A.M. accessories are machine
language programs executable at address $8400.
S.A.M.s title screen is still active when an accessry starts.

There is a number of system variables an accessory can work with :

XPOS	Byte	$0601	horizontal position for PRINT routine (00 - 79)
YPOS	Byte	$0602	vertical position for PRINT routine (00 - 23)
VALIN	Word	$0603	univarsial variable, mostly used to carry parameters
VALOUT	Word	$0605	as VALIN ; if routine gives back a parameter it is this
PULLF	Byte	$0607	0 - no Pull Down Window (PDW) open
			1 - there is a PDW open
STORE	Byte	$0609	intermittent memory for flags and registers
PULLX	Byte	$060A	x position of PDW (00 - 79)
PULLY	Byte	$060B	y position of PDW (00 -23)
PULLH	Byte	$060C	length of PDW
RMARG	Byte	$0611	right margin for CPRINT routine
BMARG	Byte	$0612	bottom margin for CPRINT routine
LMARG	Byte	$0613	left margin for CPRINT routine
XARR	Byte	$0614	x position of joystick/mouse arrow (00 - 159)
YARR	Byte	$0615	y position of joystick/mouse arrow (00 - 191)
PULLN	Byte	$0616	number of choosen desktop menu item (doubled)
COLL	Byte	$0617	0 - arrow outside PDW
			1 - arrow inside PDW
BOXX1	Word	$0622	x positon of the top/left corner of the box made by the
			BOX routine (00 - 319)
BOXY1	Byte	$0624	y position of the top/left corner of a boxmade by the
			BOX routine (00 - 191)
BOXX2	Word	$0625	x position (bottom/right); for BOX routine
BOXY2	Byte	$0627	y position (bootom/right); for BOX routine
BOXSL	Byte	$062C	X position for BOX slider (00 - 207,
			>200 --> disabled )
TEXT	Word	$062D	address of the string given back by the GETHEX routine
DIRFL	Byte	$0634	0 - show the "FREE SECTORS" message with the directory
			    in the SHOWDIR routine
			1 - don't show this message
ILEN	Byte	$0635	maximum length of the input in the INPUT routine
			(up to 45 !)
FILE	String	$5555	cotains choosen file after SHOWDIR routine
DRIVE	Byte	$507C	actual drive number (ASC code)
IBUF	String	$5568	contains input after INPUT routine
MMU	Byte	$00EC	0 - memory (from $8200 to $BFFF) changed or used
			This byte has to be set to ZERO in each accesory !!!

The zero page variables $CB to $F0 are also used by S.A.M. but can be also
used by an accessory.


There is also a number of system routines you can work with :

name		adr	job

PULLDOWN	$4039	opens PDW (latitude is 16 characters)
			Input :
			X register - x position
			Y register - y position
			A register - length
			Output :
			PULLX,PULLY,PULLH,PULLF
PULLUP		$40E1	closes PDW
INPUT		$4F83	reads a text string from keyboard
			IMPORTANT: You have to save PULLF before use the INPUT
				   routine and you have to restore it after
				   returning from it.
			Input : ILEN - maximum string length
			Output: IBUF and following - text string
				A register	   - ESC pressed (1)
						     or not (0)
GETHEX		$4BE0	writes text string to status row and reads hex value
			from keyboard
			Input :
			TEXT - pointer to text string
			Output :
			VALIN - hex value
			A register - ESC pressed (1) or not (0)
PRINT		$43E1	writes text to screen or in PDW if open
			Input :
			XPOS - x position
			YPOS - y position
			X register - Highbyte of the text string address
			Y register - Lowbyte
			A register - length of the text string
CPRINT		$43FF	writes text in screen chapter
			Input :
			XPOS - x position
			YPOS - y position
			$CC  - Highbyte of text string address
			$CB  - Lowbyte of text string address
			X register - length of the string
			LMARG,RMARG,BMARG - see description
ARROW		$40F6	controlles joystick/mouse and moves the arrow
			returns when trigger is pressed
			Output : XARR, YARR - joystick/mouse position
GETDIR		$4F2B	loads directory in the buffer at $2B00
			Input : DRIVE - drive number
SHOWDIR		$4D85	shows directory, returns when file is chosen or button
			pressed in the MENU line
			IMPORTANT : Before you start SHOWDIR you have to
				    call GETDIR and open a PDW (x=32,y=2,
				    length=17)
			Input :
			DIRFL
			Output :
			A register - 0: file chosen
				     1: exit (button in menu line pressed)
			FILE - Filename
BOX		$4CFB	draws rectangle and sets slider
			Input :
			BOXX1,BOXX2,BOXY1,BOXY2 - see description
CLRSTAT		$5031	clears status lines (row 22 and 23)
			IMPORTANT: save PULLF before and restore it after using
			this routine.
PUSHBS		$4489	copies screen to screen buffer
PULLBS		$44D3	copies screen buffer to the screen
MULT		$453D	multiplies two integers
			Input :
			VALIN - integer #1
			VALIN +1 - integer #2
			Output :
			VALOUT - result
CHAROUT		$4376	prints character on the screen
			Input :
			XPOS,YPOS - position
			A register - character code
ARRSET		$417A	sets arrow to a certain position
			Input :
			XPOS,YPOS - position
SAM		$401F	Return to S.A.M.
			the S.A.M. graphic and menu line will be rebuilt



The menu line stuff :

This is a bit more complex, so be sure that you are really willing to follow
through...

S.A.M. wasn't originally created to be an 'open' system. So there are no
administration routines for the menu line and the pull down menues suitable
in accessories.
You have to write your own (and I show you in this text how it goes).

To create a menu line you have to print 80 characters in line 0.

...
LDA #0
STA XPOS
STA YPOS
LDY #DATAFIELD
LDX /DATAFIELD
LDA #$50
JSR PRINT
...
DATAFIELD has to be a data field as this :

DATAFIELD	.AT "FILE             OPTIONS     EXIT       "
		.AT "                                        "

To let the user choose a PDW from the menu line you have to do this loop

...
LOOP	JSR ARROW
	LDA PULLF
	BNE WOPEN
	JSR CHOOSE
	LMP LOOP
WOPEN	JSR WCHOOSE
	JMP LOOP

If you want be let things happen while waiting for the user to choose a PDW
it must happen in this loop (or in an interrupt routine).

As you see there have to be two routines : CHOOSE and WCHOOSE.
But there have to be also another three data fields :

1) DTAB (for the menu line) :

Byte 0:		number of entries
Byte 1:		left margin for first entry (00 -79) in the 80 character string
		DATAFIELD
Byte 2:		right margin for first entry
Byte 3:		left margin for second entry
Byte 4:		right margin for second entry
...

or with the data field mentioned before

DTAB	.HX 03000311171D20

2) TXTAB (to control the menu lines' PDWs) :2) TXTAB (to control the menu lines' PDWs) :

In this field 4 bytes are reserved for each menu line entry. So the length
of this field is /number of entries/ * 4 .

Byte 0 :	number of entries in pull down window (PDW) #1 (*16)
Byte 1/2:	adress of the string where all PDW#1 entries are specified
Byte 3 :	ZERO (0)
Byte 4 :	number of entries in PDW #2 (*16)
Byte 5/6:	adress of the string where PDW#2 entries are specified
Byte 7 :	zero
...

or in our example :

TXTAB	.HX 40
	.DA PDW1
	.HX 00
	.HX 10
	.DA PDW2
	.HX 00
	.HX 20
	.DA PDW3
	.HX 00
PDW1	.AT "Load            Save            Directory       Format          "
PDW2	.AT "Destroy ATARI   "
PDW3	.AT "Exit to S.A.M.  Boot system     "


3) VECTOR (32 bytes for each PDW) :

This field contains the start addresses for all the routines represented by
a PDW entry.
You can put 16 entries together in one PDW routine and there are two bytes
reserved for each entry, so this field must have a length of 32*(number of
PDWs) bytes.

Byte 0/1 :	start address for routine represented by entry #1
Byte 2/3 :	start address for routine represented by entry #2
.
.
.
Byte 30/31 :	start address for routine represented by entry #16

or in our example :

VECTOR	.DA LOAD,SAVE,DIR,FORMAT,0,0,0,0
	.DA 0,0,0,0,0,0,0,0
	.DA DESTROY,0,0,0,0,0,0,0
	.DA 0,0,0,0,0,0,0,0
	.DA GOBACK,BOOT,0,0,0,0,0,0
	.DA 0,0,0,0,0,0,0,0

LOAD,SAVE,DIR,FORMAT,DESTRY,GOBACK and BOOT are labels and say where all
those routines are located in memory.


Okay, and here are both routines (CHOOSE and WCHOOSE). Those routines were
published in ATARImagazin 11/88 and were written by Andreas Binner and Harald
Schoenfeld.
The same is to say about most of the other info in this text.
But they wrote it to be public so I hope there is no problem in reprinting
it.

CHOOSE	LDA XARR
	LSR
	STA XPOS
	LDA YARR
	LSR
	LSR
	LSR
	STA YPOS
	LDA DTAB
	TAX
	LDY #0
LOOP1	LDA DTAB+1,Y
	CMP XPOS
	BCS NOTHING
	LDA DTAB+2,Y
	CMP XPOS
	BCC NOTHING
	JMP FOUND
NOTHING	INY
	INY
	DEX
	BNE LOOP1
CLOSE	JSR PULLUP
BACK	RTS
FOUND	LDA YPOS
	BNE CLOSE
	LDA DTAB+1,Y
	TAX
	STY PULLN
	STY STORE
	ASL STORE
	LDY STORE
	LDA TXTAB,Y
	LSR
	LSR
	LSR
	LSR
	CLC
	ADC #1
	LDY #1
	JSR PULLDOWN
	LDA STORE
	TAY
	LDA TXTAB,Y
	PHA
	LDA TXTAB+2,Y
	TAX
	LDA TXTAB+1,Y
	TAY
	LDA #1
	STA XPOS
	STA YPOS
	PLA
	JSR PRINT
	RTS

This routine looks if there you chose an entry in the menu line and opens it.
Please email me for further explanation.

WCHOOSE	LDA COLL
	BNE INPDW
	LDA YARR
	LSR
	LSR
	LSR
	BEQ WCBACK
	JSR PULLUP
WCBACK	RTS
	LDA YARR
	LSR
	LSR
	LSR
	CMP PULLY
	BEQ WCBACK
	BCC WCBACK
	SEC
	SBC PULLY
	SEC
	SBC #1
	ASL
	STA STORE
	LDA PULLN
	ASL
	ASL
	ASL
	ASL
	CLC
	ADC STORE
	TAY
	LDA VECTOR,Y
	STA $CB
	LDA VECTOR+1,Y
	STA $CC
	JMP ($CB)

This routine looks if you choose an entry of the open PDW and executes the
correlated routine.

Here is another short routine (to go back to S.A.M.) :

GOBACK	JSR PULLUP
	LDA #1
	STA DIRFL
	PLA
	PLA
	JMP SAM

All other routines should end with an RTS command.

I hope this was not too hard to understand...
Questions and suggestions via email to me...

--==rossi==--
Oliver Rosenkranz
rossi@cs.tu-berlin.de


Newsgroups: comp.sys.atari.8bit