.h1 = main heading
.h2 = subheading
italics are delimited by matching underscores

			    Advanced CP/M

		      Environmental Programming

			   Bridger Mitchell
------------
sidebar on Bridger
PLEASE CHANGE TELEPHONE NUMBER TO:	"213-393-6105 (evenings)"

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

.h1 BackGrounder ii Update

BackGrounder ii is like no other CP/M program -- it simply feels
different.  A touch of the "suspend" key and you pop into the
background command processor, a touch of a user-defined macro key and
you can switch to a second program, literally in mid-sentence.  The
built-in calculator, notepad, screen-dump, and cut-and-paste function
turn out to be extremely handy desk accessories, especially because
results on one screen can be exported to another task.  But the magic
of it all -- black magic, perhaps -- is the feeling that comes over
you when you first experience the screen flashing back, cursor in
place, with _no_ trace of having been away!

BGii and the Z-System stand as twin pinnacles of advanced CP/M
operating systems.  At a conceptual level, they are orthogonal.  By
providing memory buffers for the command processor and applications
and supporting conditional execution, ZCPR 3.4 allows tasks to
_communicate sequentially_.  By making the BDOS and command-processor
recursive, BackGrounder ii creates two-way _communication between
simultaneous tasks_, under user control.  When combined -- BGii
running in a ZCPR 3.4 system -- they elevate 8-bit computing into another
dimension.  The results are awesome.

Bringing BGii fully up-to-date to support the latest ZCPR version 3.4
has been a largely enjoyable task.  I had put it off more than once,
wanting to finish up DosDisk and then Z3PLUS.

When I finally returned to the BGii code I was pleasantly surprised to
uncover several new coding shortcuts.  They enabled me to squeeze in
almost all of the "Z34" features and add some new conveniences,
including enabling the user to rename the built-in BGii commands.
Expert testing by Cam Cotrill and Jay Sage greatly firmed up several
soft spots.  It's now the production version and licensed users can
order an update at low cost.


.h1		    Environmental Programming

A customer of long-standing called the other night, as I was drafting this
column.  He enthused about BackGrounder ii, but then noted that "it
sometimes finds bugs in _other_ programs!"

Alas, bugs are always with us, even when we think we've got our own
code pretty solid!  This column is going to be about writing code that
is respectful of the environment in which it is running.
The sage (Sage?) advice collected here, and culled from the
programming experience of many old hands, surely won't eliminate bugs.
But it will greatly increase the chances of your programs living more
harmoniously with a wide variety of CP/M systems.


.h2  Make a good start

The command processor starts your program by _calling_ it. This means
that you can speed up the flow of jobs by _returning_ to the CCP when
your program terminates, instead of causing a warm boot that reloads
the CCP.  To do this, you must _save the stack pointer_ and stay clear
of the CCP in the 2K of memory just below the BDOS.

_Use a local stack_ for all but the simplest programs.  The command
processor's stack may not be deep enough for your functions, BIOS
calls, and interrupts.  And that stack could be in the TPA, part of
the CCP that may be overwritten by your program or data.

.h2 Know the Territory

A shockingly large number of programs assume that they will always be
run only in the environment for which they were written.  Drop them
into a different world and they almost always injure their host.
So, please, join the environmentalists and take the responsible
programmer's oath: _Do No Harm!_ Survey the territory before plunging
ahead, and pose these questions:

Is our host a Z80?  An HD64180?  A Z280?  That determines which opcodes can
we safely use.
 
Is our host running CP/M Plus? or ZSDOS?  What system calls are available?
Is DateStamper running?

Is one of the drives set to MS-DOS format under DosDisk?  If so, we
must not make assumptions about internal data in the file control
blocks on that drive or about the structure of the disk directory.

Is the host running a Z-System?  With an extended environment?  If so,
we should allow for possible non-standard sized BDOS and CCP modules
and get their addresses from the environment.  If it is _not_ a
Z-System, we must avoid any references to Z-environment parameters;
if we are a Z-tool, put out a short message of requirements and quit.

Finally, if we should need to know, can we determine what BIOS and type of
machine our host is?

Figure 1 is a routine called TERRITORY that does these checks.
It should be called at the very beginning of a program.  If the host
system has a Z-System command processor (ZCPR 3.3 or later, or
BackGrounder ii) the program will begin with the HL register
containing the address of the Z-System external environment.

TERRITORY first checks for a Z80-compatible processor, and then uses
obscure differences in register operations to identify HD64180 and
Z280 processors.  The system addresses (BIOS, BDOS, and CCP) are
determined from a Z-System extended external environment, if there is
one, so that non-standard BDOS and CCP modules can be used correctly.

The BIOS check demonstrates how to detect an NZ-COM system and find
the address of the original CBIOS.  Several systems have bios-specific
references to such things as function-key tables, foreign disk
parameter blocks, and extended BIOS functions that cannot be located
from the address at 0001h when NZ-COM is running.

You can use the flags and addresses established by TERRITORY for your
own requirements.  You might also want to make a version of it into a
simple diagnostic tool that prints out messages identifying exactly
what the host system consists of.


.h2 Identify yourself

Unless yours should be a silent program, announce yourself to the
user with an appropriate message that includes a version number.
All programs change, get updated, and gain features.  You and other
users need to be able to identify which model they're driving.
Most Z-System tools use a standard format, which is well worth
adopting for other programs:

   A>PROGNAME Vers. 1.5 -- terse functional description

If you are the silent type, include sufficient version identification
in the data area so that a debugger can be used to inspect the
program.  Alternatively, include the information in a help screen.
Z-System tools use the standard "double-slash" command line to request
help, another worthwhile convention:

  A>PROGNAME //



.h2 Protect the Environment

_Save the current drive and user number_, so you can restore them on exit.

Explicitly _allocate memory_ and check to prevent overflowing the
available transient program area.  The TPA is always the memory from
100h to the value that is stored at 0006, less 1 byte.

If there are no RSX's in memory, that value is the entry address of
the BDOS and is the target of the jump instruction at 0005.  This is
the most common case; in CP/M 2.2 the CCP will occupy 6 + 800 hex
bytes below that.  But if an RSX has been loaded, its address
will be at 0006. In that case the CCP will already be protected, and
you can use all of the TPA and still return to the CCP. 

So, if no RSX is loaded, if you intend to return to the CCP, and if you
are not running under CP/M Plus, allow 2K of space below the BDOS.
Figure 2 gives a routine that makes this calculation.  It calculates
the largest usable memory that will still preserve the CCP and returns
the address of the first byte beyond that.

Applications have the right to have their register values treated
systematically when they call on the operating system for services.
CP/M is an 8080-based operating system, and from the beginning it put
programmers on notice that it would not preserve the user's registers.
That was logical, as the OS needed most of them for returning values.

The introduction of the Z80 and subsequent 8080-compatible CPUs led to
more compact and more efficient BIOSes.  Unfortunately, more than one
BIOS writer began using the additional _Z80 registers_ without
preserving their values for the user.  The consequences have been
erratic havoc -- programs test out flawlessly on a variety of systems,
then fail to start, or die mysteriously on another machine.

The environmentally-conscious rule here is: if your code will become
part of the operating system -- the BDOS, BIOS or an RSX extension --
save and restore all Z80 registers you use.  Why?  Simply because it's
a far greater burden on an application to preserve IX, IY, AF', BC',
DE', and HL' in order to run on an arbitrary system, than it is for
the system programmer to protect exactly those registers he needs to
use.

The extreme case of environmental wantonness is a rom-based-based BIOS
for the early Osborne Executive, which used alternate Z80 registers
for an interrupt service routine, without preserving them!  A moment's
thought should persuade you that there is _no way_ an application
could _ever_ use those registers and run on that machine.  Was the
system designer so naive as to think that only 8080-code would ever be
run on an Executive?


.h2  Expect the Worst

_Test for all disk errors_.  Proceeding after one error (a full disk,
a non-existent file, ...) can wreak disaster.

_Have a recovery strategy_.  Tell the user enough about the problem
that he can alter the environment and try again.  Give him a
choice (insert a disk, restart the program, exit, ...).
 

.h2 Limit the Damage

Before writing a file, check the disk space remaining.  If there isn't
enough room, give the user the chance to delete something, or to insert a
new disk.

If a write error occurs, try to close the file to save as much data as
possible.  Offer the user a second chance, by changing disks or
drives.  Clean up file fragments after recovering.

Before printing, test to see if the printer is ready.  If it isn't,
ask the user to make it ready before retesting.  Otherwise, if you
start sending characters, the computer will hang and you can't inform
the user what's wrong.  A short routine to do this, derived from
BackGrounder ii, is shown in Figure 3.  It's important to send a test
character (a carriage return) in order to actually test the _printer_
itself, because a serial printer channel will normally have a UART
with a one-character buffer.  If the UART's buffer is empty, it will
report that _it_ is ready to receive a character, even if the printer
isn't.


.h2 Don't take shortcuts

The TERRITORY routine doesn't check for Z-Systems earlier than ZCPR
version 3.3 (which supplies the external environment address in HL
when it calls each program).  It can be extended to do so by searching
memory for the "Z3ENV" string and verifying that the self-reference
address indeed points to the environment area being examined.

Note that if the string is found, but the address test fails, the
search must be continued; it's quite possible to have more than one
"Z3ENV" string in memory.  Jay Sage tells me there is a group of
programs that, regrettably, take a shortcut and stop searching on the
first match.  They fail to run on his system because it includes,
quite appropriately, a directory named "Z3ENV".

The new Z3PLUS and NZ-COM systems have exposed shoddy programming
practices, bugs that have been hibernating in widely used utilities.
A common one results from the faulty assumption that the Z-System
external environment address began on a memory page (xx00 hex).
When this happens to be the case, then:

	ld	l,offset

is a shorter route pointing to an environment parameter than:

	ld	de,offset
	add	hl,de

But when it's not, the path leads over the cliff.



.h2 Clean up

_Use a common exit_ point.  This makes it easier to ensure that
nothing is overlooked as your program grows to include new branches.

_Close open files_ and _delete temporaries_. 

_Restore the default drive and user_.

If you've used full-screen terminal features, _leave a clean screen
below the cursor_.  For some applications you may want to clear the
entire screen.  In other cases, having the final lines of data remain
allows the user to make use of the information when she or he enters
the next command; in that case, put the cursor on the bottom line and
send a newline.

Finally, if you have not overwritten the CCP, restore the stack and
return.  Otherwise warmboot.


I certainly don't follow these guidelines slavishly, though I do
pay them regard before releasing any software for wide testing. 
My own temporary programs, run in a known test environment, are
often rude, slap-dash pasteups to get the job of the moment done
rapidly. But I guard against giving them out to others.  It's no
favor to pass on code that may explode a friend's system at some
unsuspecting moment.  Which leads me to recall ...


.h1		   A Tale of Too-hasty Design

Some months ago a well-known programmer, author of CP/M several
BIOSes, gave me a copy of the BIOS to a particular new computer. 
I was developing customized operating-system code for this
box, and had a similar machine for the debugging and testing
cycle.  I had re-assembled the BIOS, made several rounds of
modifications that were converging to a stable new system running
on my box when, poof, I exited from a program and the system
went to lunch.  It wouldn't reboot, even from power up.

A systems programmer learns (from bitter experiences!) to sit
quietly, write down everything he can remember, and think long
and hard before he touchs anything besides a pencil. Some clues
to the crash may remain behind, on disk or in memory (although in
this case memory was fully reset).  In this case, the A: drive
had been a ram disk with uninterruptible power, so I assumed that
its system tracks had somehow been damaged.

I decided to make a systematic tour of the A: disk drive by booting up
from a floppy system, and looking at different tracks with DU.  (Yes,
I try always to have a couple of bootable systems stored away on
floppies for that black day that a hard-disk or ramdisk goes bad.  You
should too.)  Sure enough, I found what appeared to be file data in
the directory tracks.  More investigation disclosed that the following
tracks, which should have been the directory, had also been corrupted.
I took a deep breath, made a mental note to write down what I could
still remember of what I had typed in during the last two hours of
iterations since backing up the experimental system code.  I continued
checking the disk.  Suddenly, several tracks later, the disk appeared normal.

What could cause such systematic damage?  Hypotheses poured forth,
only to be discarded.  Finally, I saw the glimmer of a pattern.
The start of the ram disk -- the start of banked memory --contained
data related to the data at the very end of the disk.  Wraparound!
The BIOS had literally gone off the deep end of the ram disk and
started writing on the front, clobbering the system, the
directory, and the first files after that.  As soon as a warmboot
was attempted, the system loaded the corrupted system track and
was dead.

A hot theory.  But where was the bug?  I consulted with the
author, and then he remembered --  he'd given me the _large_
ramdisk version of the BIOS.  With less ram installed on my
box the addressing had wrapped around.

I wasn't pleased to learn he'd overlooked putting in a _runtime_
check for the amount of memory the system possessed.  A simple
test to make, yet because it was omitted, I now had several hours
of reconstructing and testing files ahead of me.

This bug was in hibernation, waiting to byte just when a large
disk filled up.  Only extreme testing is likely to have disclosed
it before it zapped a directory on a customer's machine.  We were
lucky it happened when it did.  Yet it could have been prevented,
by systematic design.  Environmentally conscious programming
would have done it.


.h1			Identifying the BIOS

How can a program determine who its host is?  What hardware is
available?  Digital Research (DRI) had no BDOS function to return a
version number in CP/M 1.4 and never did introduce one for identifying
the BIOS.  I have no idea why DRI failed to anticipate this question;
a BIOS call to return version information seems now the obvious way to
do things.  And MSDOS is no better.

Anyway, we are stuck with CP/M's warts; there is no _portable_ BIOS
call that will identify an Ampro from a Kaypro from an S-100 box.
Even if _a particular_ manufacturer had the vision to include this
entry point, it's catch-22.  We can't safely use the call until we know
that it's available!

The best approach is to identify the BIOS by reading memory bytes in
the BIOS.  Every BIOS should include a unique signature and version
information.  The signature can be an ascii string, such as "PPS" (in
the Advent/Plu*Perfect TurboRom BIOS) or "XBIOS" (in the XBIOS for
SB180's), at a known offset from the start of the BIOS.  Once the
program has identified the type of BIOS, it knows it can make an
extended BIOS call, if one has been provided, to obtain additional
information.  The XBIOS system, for example, provides information on
the available hardware devices and their corresponding ascii names in
the system.

The TERRITORY routine includes a ck_bios routine to identify Kaypro
systems with a TurboRom BIOS and systems running NZ-COM.  Other checks
can be added to identify other particular systems.

Unfortunately, a number of BIOS's were written by people who
apparently never thought others might write software for their very
computer!  In these cases, the safest approach is to tell the user in
a message that the type of BIOS cannot be determined, and ask him to
confirm or enter the model manually before proceeding.


;   Figure 1.  Determine characteristics of CP/M host's environment
;   _______________________________________________________________


bdos	equ	5

; Call this routine immediately.
; Enter with HL = value from command processor.
;
TERRITORY:
;
; Test for z80-compatible cpu.
;
	sub	a		; sets even parity in 8080
	jp	po,ck_180
	ld	c,9		; announce Z80 requirement
	ld	de,notz80msg
	call	bdos
	rst	0		; ..and exit to warmboot
;
; Test for HD64180/Z180
;
ck_180:
	ld	bc,101h		; prepare to multipy B=1 x C=1
	db	0EDh,04Ch	; MLT BC opcode
	dec	b		; if Z80, B will be unchanged 
	jr	z,ck_280	;
	ld	a,c		; 180 leaves 16-bit result (1) in BC
	ld	(z180flag),a
;
; Test for Z280

ck_280:	ld	a,10		; Z280 doesn't use refresh register
	ld	r,a		; load it
	ld	c,a		; save it
	ld	b,a		; cause some refreshes
loop:	djnz	loop
	ld	a,r		; if value hasn't changed
	cp	c
	jr	nz,ck_rest
	ld	(z280flag),a	; ..it's a 280
;
ck_rest:
	push	hl		; save possible env address from ccp
	call	ck_dos		; check type of BDOS
	pop	hl
	call	ck_z3		; check for Z-System
	call	ck_dosdisk	; check for DosDisk
	call	ck_bios		; check type of BIOS
	call	ck_bg		; check for BackGrounder ii
	ret

;
;
; Check for BDOS version 
;
ck_dos:	ld	c,12		; get CP/M version number
	ld	e,'D'		; with DateStamper id request
	call	bdos
	cp	30h
	jr	c,ck_ds
	ld	(cpm3flag),a	; set flag if CP/M 3
	ret
;
; Check for DateStamper
;
ck_ds:
	cp	22h
	jr	nz,ck_xdos	; .. not CP/M 2.2
	ld	a,h
	cp	'D'
	jr	nz,ck_xdos	; ..no DateStamper
	ld	(dsflag),a	; set flag
	ld	(dsclock),de	; and save clock pointer
;
; Check extended dos version
;
ck_xdos:ld	c,48		; use extended version number call
	call	bdos
	ld	(dosvers),hl	; save version number and type
	ret

;
; Check for Z-System.
; Enter with HL = value from command processor.  If ZCPR 3.3
; or BackGrounder ii, HL -> external environment
;
;
ck_z3:	push	hl		; save possible ENV address
	inc	hl		; Offset to 'Z3ENV'
	inc	hl
	inc	hl
	ld	b,Z3ENVLEN
	ld	de,z3envsig
	call	match
	pop	de		; recover de = ENV address
	jr	nz,set_std
	ld	hl,1Bh		; Offset to self-reference address
	add	hl,de
	ld	a,(hl)		; Check low byte
	cp	e
	jr	nz,set_std
	inc	hl
	ld	a,(hl)		; Check high byte
	cp	d
	jr	nz,set_std
;
	ld	(zsysflag),a	; set flag
	ld	(z3env),de	; save environment address
	ld	hl,08h		; get env. type
	add	hl,de
	ld	a,(hl)
	and	80h		; test for extended type (>= 80h)
	ld	(extenvflag),a	; and save result
	jr	z,set_std
;
; Set system addresses for a Z-System with an extended environment

	ld	hl,45h		; -> bios address in environment
	call	addderef
	ld	(biosbase),hl
	ld	hl,42h
	call	addderef
	ld	(bdosbase),hl
	ld	hl,3Fh
	call	addderef
	ld	(ccpbase),hl
	ret

;
; Set system addresses for a standard system.
;
set_std:
	ld	hl,(0001h)
	ld	l,0
	ld	(biosbase),hl
	ld	de,-0E00h
	add	hl,de
	ld	(bdosbase),hl
	ld	de,-800h
	add	hl,de
	ld	(ccpbase),hl
	ld	a,(cpm3flag)	; if not CP/M Plus
	or	a,a		; ..all done
	ret	z
;
	ld	c,49		; for CP/M Plus, w/o extended environment...
	ld	de,getscbpb	; get system control block address
	call	bdos
	ld	l,98h		; offset to address of resident bdos
	call	deref		; dereference pointer
	ld	l,0
	ld	(bdosbase),hl
	ld	hl,100h
	ld	(ccpbase),hl
	ret
;
addderef:
	add	hl,de		; offset pointer by DE
deref:	ld	a,(hl)		; dereference HL pointer
	inc	hl
	ld	h,(hl)
	ld	l,a
	ret
;
match:	ld	a,(de)		; match B bytes at DE, HL
	cp	(hl)
	inc	hl
	inc	de
	ret	nz
	djnz	match
	ret

ck_dosdisk:
	ld	c,113		; get DosDisk id
	call	bdos
	cp	0FDh
	ret	nz		; ..if not DosDisk, quit
	ld	(dosdiskflag),hl; set flag (L) and drive with MS-DOS format (H)
	ret


ck_bios:
	ld	hl,(0001h)	; -> normal CBIOS warmboot address
	ld	l,90		; -> NZ-COM id in NZ-COM pseudobios
	ld	de,nzname	; if NZ-COM id is exactly there
	ld	b,NZNAMELEN
	call	match
	jr	nz,ck_turbo
	ld	hl,(z3env)	; ..get CBIOS (page) addr from
	inc	hl		; ..z3env+2
	inc	hl
	ld	h,(hl)		; ..get page
	ld	l,0
	ld	(biosbase),hl	; ..and save correct ptr to CBIOS
;
; Check for Kaypro TurboRom
;
ck_turbo:
	ld	hl,0FFF8h	; -> location of TurboRom signature
	ld	b,TURBOSIGLEN
	ld	de,turbosig
	call	match
	ret	nz
	ld	(turboromflag),a; set flag
	ret

;
; Check for BackGrounder ii
;
ck_bg::	ld	hl,(bdosbase)	; -> location of BGii signature
	push	hl
	ld	de,-800h+5Bh	; in BGii CCP
	add	hl,de
	ld	b,BGSIGLEN
	ld	de,bgsig
	call	match
	pop	hl
	ret	nz
	ld	(bgflag),a	; set flag
	ld	de,-800h+1	; -> BGii ccp entry +1
	call	addderef	; get that address
	dec	hl		; BGii task flag is 1 byte lower
	ld	(bgtaskptr),hl	; save ptr to task flag
	ret
;
notz80msg:
	db	'Not Z80.$'
getscbpb:
	db	3Ah		; return address of scb
	db	0		; "get" code
;
; Z-System environment signature
;
z3envsig:
	db	'Z3ENV'
z3envlen equ $-z3envsig
;
; NZ-COM's  signature in the pseudo-bios, at offset 90.
;
nzname:	db	'NZ-COM'
nznamelen equ $ - nzname
;
; BackGrounder ii's signature

bgsig:	db	'BGii'
bgsiglen equ	$ - bgsig
;
; Kaypro TurboRom signature, at FFF8h
;
turbosig:db	'PPS'
turbosiglen equ $ - turbosig
;
;
; System flags (any NZ value means TRUE)
;
z180flag:	db	0	; HD64180/Z180 cpu
z280flag:	db	0	; Z280 cpu
cpm3flag:	db	0	; CP/M Plus
dsflag:		db	0	; DateStamper
zsysflag:	db	0	; Z-System (ZCPR 3.3 or later)
extenvflag:	db	0	; extended Z-System environment
bgflag:		db	0	; BackGrounder ii
turboromflag:	db	0	; Advent/Plu*Perfect Turborom
;
dosvers:	db	0	; } a pair  version number (hex)
dostype:	db	0	; }         'S' = ZSDOS, 'D' = ZDDOS, 0 = ZRDOS
dosdiskflag:	db	0	; } a pair  DosDisk
dosdrive:	db	0	; }	    MS-DOS format drive
bgtaskptr:	dw	0	; BGii internal flag pointer: bit 1 set = upper task
;
; System Addresses
;
z3env:		dw	0	; Z-System external environment
biosbase:	dw	0	; BIOS
bdosbase:	dw	0	; BDOS
ccpbase:	dw	0	; CCP
dsclock:	dw	0	; DateStamper clock




;     Figure 2.  Find Top of Usable Memory that Preserves the CCP
;     ____________________________________________________________


; Return HL = top of usable memory + 1
;
top_of_mem:
	ld	hl,(0006)	; load protect address
	ld	a,(cpm3flag)	; if CPM Plus
	or	a		; 
	ret	nz		; ..return it
	push	hl		; for CP/M 2.2
	ld	de,(ccpbase)	; if protect address is below CCP
	sbc	hl,de
	pop	hl
	ret	c		; .. return it
	ex	de,hl		; else return CCP address
	ret



;		   Figure 3.  A Printer-Ready Test
;                  _______________________________

; Return: NZ if printer is ready
;
test_list:
	call	b_lstat		; if printer is busy
	ret	z		; ..return
	ld	c,0dh		; send carriage-return
	call	b_list		; ..to flush UART buffer
	call	wait		; allow printer to process it
				; and re-test status
b_lstat:ld	de,2dh-3	; call BIOS list-status entry
	call	bcall
	or	a,a
	ret
;
b_list:	ld	de,0fh-3	; call BIOS list entry
bcall:	ld	hl,(0001)
	add	hl,de
	jp	(hl)


wait:
;	...			; any 10-20 mS routine
	ret