PROGRAM PITSTOP
Your Sinclair, January 1989

[McCandless only made two mistakes in the listings this month,]
[but the improvement wasn't to last.                      JimG]

Brush the snow off your tyres and put your Speccy in gear, 'cos
it's time for the latest trip to the pit with David McCandless.

This month sees a return to a normal edition of Pitstop, after our
recent aberrant excursions into the wild world of screen effects. And
seeing as Chrimble is upon us again, and a substantial holiday is in
sight, what better way to while away the short snowy evenings than
with a Speccy, a TV, and pages of perfect [Hah! JimG] programs, gift
wrapped in hex? Scrummy.

Just feast your eyes on this huge array of listings. Mmm. There's a
documented assembly-languaged program (the work of my friend and
yours, Graham Mason) which will [not] be a regular feature in future
issues. It's one of the new ideas I shall be phasing in over the next
few frosty months. So keep your eyes peeled and your potatoes open.
(Eh? Ed).

There's also the response to the challenge for the password program
from Kevin Lea who is one of the winners. And then after that, you can
happily mimic those 128K menus with Peter Kecskemety's program. And
finally fill up those ugly vacuous line drawings using a fill routine
written by regular contributor Chris Pile.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

A LA CARTE
by Peter Kecskemety

Ever looked at the menus on the 128K Speccy and thought "Gosh, they
look impressive"? No? I didn't think you had. Okay, so they don't
exactly look impressive, but they're useful you know, and "useful" is
a good word if you're on the lookout for a routine that you want to
use.

Stunningly enough, a program to emulate the 128K menus is exactly what
Peter J. Kecskemety has delivered to my door. Now there's a coincidence.
Let's have a look at it.

A LA CARTE
Just in case you're wondering, the menus we're talking about are kinda
rectangular, garishly coloured, and have irritating little coloured
stripes on the top which make your eyes water if you turn up the
colour too much.

And with Pete's little (587 byte) program you can copy every facet of
those magical boxes, position them anywhere on-screen, fill them with
anything, define the background colour, highlight the options and
title colour, and then select a specific option. Cor.

FOR STARTERS ...
Firstly, use the hex loader program (from Password) to enter the hex
block. Then, save the code with SAVE "name" CODE 64696,587.

If you wish, you can type in the demo to see what 128 owners experience
every evening (fwar).

THE MAIN COURSE
Before you dive into the menu you must decide what you're going to put
in it. It can be anything from the days of the week to the different
makes of biro you keep in your pencil case. While pondering over this
problem, decide on your colour scheme:

POKE 64696, background colour
POKE 64697, option highlight
POKE 64698, title colour

Once you've POKEd in these variables, use the following method to
create your menu:
PRINT USR 64700;AT x,y;"TITLE","OPTION1","OPTION2","OPTION3" etc
So if you wanted to make a menu of your top three rave albums at
screen co-ordinates 2,7 you'd:
PRINT USR 64700;AT 2,7;"Dave's Fave Raves","The Soul Mining","The
Infected","The Dog Containers"
Simple or what? But if you're still perturbed have a peek at the demo
program to see how that works.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =


PASSWORD
by Kevin Lea

A couple of months back I said "Gimme a machine code password routine".
Remember? I had expected to sit back and watch a mere two or three
entries trickle in through the letterbox, but I received no less than
21 replies! Wow!

What a torture it proved to be evaluating them all. I toiled, sweated
and toiled some more and finally managed to produce two winners. The
first one is Kevin Lea, whose short, friendly, and utterly powerful
program, grabbed me by the decisive nodules (gwar) and wouldn't let
go. (I'll be printing the second routine in a later edition of Pitstop.)

WORRA LORRA FEATURES
Here are some of the features at your fingertips:
* Completely relocatable anywhere in memory.
* Print any message anywhere on-screen.
* Passwords can be up to 255 characters long.
* The key repeats can be hurried or slowed for varying typing speeds.
* Either 'crash' or 're-try' option.
* All keys, numbers and symbols can be in a password.
* The input line can go anywhere.
* Can be any colour.
* Will work on any Spectrum..

PASS THE WORD
It's easy, it's peasy, it's .... erm ... queasy! Just jam the BASIC
program into your Speccy and RUN it.


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =


FILL IT
by Chris Pile

[The first line of the BASIC listing was missed off, but the full listing   ]
[was printed in the September 1993 issue (only four+half years later!). JimG]

You have to admit that line drawings are pretty ugly (Huh? Ed).
They're so bleak, so boring, so blatantly empty. Do you know what they
need? They need a fast and accurate fill routine. Cue Chris Pile.

Chris, quick to follow up his superswift Circle routine has come up
with a downright rapid "spill-fill" routine. Stunningly quick,
accurate, and short. It'll make you speechless.

BUT HOW?
Simple is too small a word to describe how easy this routine is to
work. With the aid of the notorious hex loader type in the code,
saving it with SAVE "name" CODE 60160. [Of course, without the length
parameter (180) this command is invalid. There was no hex listing,
anyway; the code was in DATA statements as part of the demo program.
JimG] Then, the future, before you load it CLEAR 60159 to ensure that
your ULA doesn't go bang. Now, type in the short demo program and
you're away ...

FULL UP
If you want to be cocky or just plain old condescending then use the
following to fill things independently:
POKE 60168,x(0-255)
POKE 60169,y(0-192)
RANDOMIZE USR 60170


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =


BORDER FX
by Graham Mason

[The TABLE label in the assembler listing was undefined, but it was]
[pretty obvious where it should go.                            JimG]

Graham Mason's Border Effects routine is a rather good example of
effective illusion. And it gives a superb impression of how fast
machine code really is.

Using interrupts, the routine changes the border colour in sequence
every 50th of a second. The result is a "solid" bar effect, right in
the border. Take it from me, it's stunning.

I've taken the program apart, split it into sections, and
disembowelled it for your use. I hope it helps you or at least gives a
rough idea of Z80 assembly language.

You'll need an assembler to type in the listing. Any will do. But note
that the '#' before some numbers indicates hexadecimal numbers. Some
assemblers differ in notation. It's best to check the manual first.

This instruction (used in all assemblers) designates the ORiGin address
of your code. In this case it's 60000, although it can be anything between
16384 and 65535.
0000            00000         org  60000

Disables all maskable interrupts and makes the program run slightly faster.
EA60 F3         00000         di

Creates a vector table at 32768 which contains the address the interrupts
jump to every 50th of a second (#9090).
EA61 210080     00000         ld   hl,#8000
EA64 110180     00000         ld   de,#8001
EA67 010101     00000         ld   bc,#0101
EA6A 3690       00000         ld   (hl),#90
EA6C EDB0       00000         ldir

Places a jump statement at this address.
EA6E 3EC3       00000         ld   a,#c3
EA70 329090     00000         ld   (#9090),a

Now at #9090 the interrupt routine is told to jump to the border effects
routine.
EA73 2182EA     00000         ld   hl,INTER
EA76 229190     00000         ld   (#9091),hl

Points the interrupt register to the high byte of the vector table.
EA79 3E80       00000         ld   a,#80
EA7B ED47       00000         ld   i,a

Selects interrupt mode two and enables interrupts. The border effects will
start working at this point. IM 2 is the mode allowing you to use your own
interrupting programs in preference to the ROM's.
EA7D ED5E       00000         im   2
EA7F FB         00000  GRAY   ei
EA80 18FD       00000         jr   GRAY

Saves all registers used on the stack. This must be done at the start of every
routine to prevent corruption.
EA82 F5         00000  INTER  push af
EA83 C5         00000         push bc
EA84 E5         00000         push hl
EA85 D5         00000         push de

Border black.
EA86 AF         00000         xor  a
EA87 D3FE       00000         out  (#fe),a

This delay here is the amount of time the border is off between lines.
EA89 0B         00000  DELAY  dec  bc
EA8A 78         00000         ld   a,b
EA8B B1         00000         or   c
EA8C 20FB       00000         jr   nz,DELAY

Points HL to the colour table.
EA8E 21F8EA     00000         ld   hl,TABLE

Register A holds the contents [pointed to by] HL (that's the next byte from
the table).
EA91 7E         00000  COLLEC ld   a,(hl)

Checks to see if the end of the table has been reached (marked by #FF), 
if so then branch off to STDATA.
EA92 FEFF       00000         cp   #ff
EA94 CAA8EA     00000         jp   z,STDATA

Change the border to the colour specified by the table.
EA97 D3FE       00000         out  (#fe),a

Register BC holds the amount of time the border colours remain on the screen.
Increase the value for thicker lines.
EA99 010600     00000         ld   bc,6
EA9C 0B         00000  DELAY1 dec  bc
EA9D 78         00000         ld   a,b
EA9E B1         00000         or   c
EA9F C29CEA     00000         jp   nz,delay1

Clear the Carry flag and loops back until done.
EAA2 E6FF       00000         and  #ff
EAA4 23         00000         inc  hl
EAA5 C391EA     00000         jp   COLLEC

Points HL to the start of the table again.
EAA8 21F8EA     00000  STDATA ld   hl,TABLE

Another delay controlling the distance between the top and bottom bars.
The longer the delay the further apart and vice versa.
EAAB 016E07     00000         ld   bc,#76e
EAAE 0B         00000  DELAY2 dec  bc
EAAF 78         00000         ld   a,b
EAB0 B1         00000         or   c
EAB1 20FB       00000         jr   nz,DELAY2

Register A holds the contents [pointed to by] HL in preparation for "printing"
the second bar. If the end marker appears this time then a key scanning routine
is activated.
EAB3 7E         00000  DATA   ld   a,(hl)
EAB4 FEFF       00000         cp   #ff
EAB6 CACAEA     00000         jp   z,KESCAN

Change border.
EAB9 D3FE       00000         out  (#fe),a

Another delay, this time for bar two.
A JP instruction is quicker than a JR instruction.
EABB 010600     00000         ld   bc,6
EABE 0B         00000  DELAY3 dec  bc
EABF 78         00000         ld   a,b
EAC0 B1         00000         or   c
EAC1 C2BEEA     00000         jp   nz,DELAY3

Loop back round until finished.
EAC4 E6FF       00000         and  #ff
EAC6 23         00000         inc  hl
EAC7 C3B3EA     00000         jp   DATA

Scan for SPACE, along the bottom left five keys of the keyboard (coded #7F).
Jump to the rotate routine if space is not pressed.
EACA 3E7F       00000  KESCAN ld   a,#7f
EACC DBFE       00000         in   a,(#fe)
EACE F6E0       00000         or   #e0
EAD0 FEFE       00000         cp   #fe
EAD2 200E       00000         jr   nz,BACKIN

Turn off the border effect.
EAD4 F3         00000         di

POP the registers off the stack in the reverse order to which they were PUSHED.
EAD5 D1         00000         pop  de
EAD6 E1         00000         pop  hl
EAD7 C1         00000         pop  bc

Set the I register back to normal, in tune with BASIC.
EAD8 3E3F       00000         ld   a,#3f
EADA ED47       00000         ld   i,a

Re-select the ROM's interrupt mode.
EADC ED56       00000         im   1

Restore A and the flags (F).
EADE F1         00000         pop  af

Enable interrupts. Very important when returning to BASIC to prevent "hanging".
EADF FB         00000         ei

Use the ROM error routine, returning with OK 0:1.
EAE0 CF         00000         rst  #8
EAE1 FF         00000         defb #ff

This useful routine shifts the contents of the table so that on every
re-print the bars appear to rotate round.
EAE2 3AF8EA     00000  BACKIN ld   a,(TABLE)
EAE5 21F9EA     00000         ld   hl,TABLE+1
EAE8 11F8EA     00000         ld   de,TABLE
EAEB 010D00     00000         ld   bc,#d
EAEE EDB0       00000         ldir
EAF0 2B         00000         dec  hl
EAF1 77         00000         ld   (hl),a

Restore all stacked registers.
EAF2 D1         00000         pop  de
EAF3 E1         00000         pop  hl
EAF4 C1         00000         pop  bc
EAF5 F1         00000         pop  af

Return to BASIC with interrupts still running.
EAF6 ED4D       00000         reti

EAF8 06070605   00000  TABLE  defb 6,7,6,5,4,3,2,1,1
EAFC 04030201
EB00 01
EB01 01020304   00000         defb 1,2,3,4,5,0,#ff
EB05 0500FF


= = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = =


So come on! Send in those programs to impress your friends, impress
yourself, and impress those software companies. I know you want your
name in emboldened lights among these wise words. Go on, send them to
Me (well David McCandless really but it's such a mouthful) Program
Pitstop, YS, 14 Rathbone Place, London W1P 1DE.

And don't forget. If your routine is a bit "good" then you'll get paid
as well! Can't be bad. Plus the big monster of technology has caught
up with us and the best program every month will be placed on MICRONET
for all you hackers to down-load.
