Date   : Tue, 27 Dec 1988 11:05:13 PST
From   : Bridger Mitchell <bridger%rcc@rand.org>
Subject: Passing Z3ENV to BDS-C

David O Goodman requested suggestions for passing the system's
external environment address to a BDS-C or other high level
language application.

This is a sketch of an approach that should be usable with most any
existing .COM file.  It requires patching together the final .COM
(after linking the BDS-C relocatable modules)j.

The standard Z-System application begins with this structure
(addresses are when loaded to 0100h):

       0100:   jp      start           ; 
       0103:   db      'Z3ENV',1       ; signature for ZCPR command processor
       0109:   dw      0000            ; where ZCPR puts z3env address

When the ZCPR 3.3 or 3.4 command processor loads a COM file to 100h
and finds the 'Z3ENV' signature at 103 it "installs" the z3env
external environment address at 109.

Append a copy of the first 10 bytes of the linked .COM file to the end
of the file.  Follow that with some startup code:

       image100:
               ds      10

       start:  ld      hl,(0109)               ; save z3env address
               ld      xxxx,hl                 ; at a known, safe location
               ld      hl,image100             ; restore the original
               ld      de,100                  ; code at 100
               ld      bc,10
               ldir
               jp      100                     ; and execute it

The address xxxx needs to be known, at compile/link time, 
to your HLL routines.  On most systems 003Bh will be ok, just following
the RST 38 jump location.  Another possibility is to check the BDS-C
runtime library's locations for storing pointers to the parsed
command line.  I remember there being room for perhaps 30 pointers; in
almost any application the 30th should be free!

I believe this patching process can be largely automated into a ZEX
script that loads a debugger, which then loads the .COM image, and
finds the end of the image from the address of the external data area
in the first bytes of the BDS-C header. The code above can the
be assembled in the debugger, using a "load hl direct" instead
of "ld hl, image100", and the 10 bytes moved with the debugger's
Move command.

This approach should run on any Z-System, including Apples with
"non-readable" high memories.  The C code should check the z3env value
for non-zero before using it, for the cases in which the code runs on
a non-ZCPR 3.3 or 3.4 system.  In fact, this test should really also
fail if the patch itself has not been made to the linked BDS-C file.
(That may be a good reason to choose a free NUL word inside the BDS-C
library for the xxxx address).  And the startup code should be
extended to include a Z-80 test.

When you have a smooth approach, please post an application note "for
the rest of us"!

Marc Wilson suggested the approach of scanning high memory for the
string 'Z3ENV'.  This technique, necessary for pre-ZCPR version 3.3
systems, needs to be made rigorous.  After finding a match, the
routine must check that the "self-reference" address in the z3env
structure does, in fact, agree with the address at which the match has
been found, and, if not, continue searching.  High memory may contain
several Z3ENV strings -- a named directory, or the host disk buffer.


-- bridger