GET_ENV$
                               ========

This is a package of routines to access Environmental Variables (EV) as
found in ENV_BIN, from assembler. GET_ENV$ is just a proof of concept
keyword to collate these routines and their help routines in one place.

There are already keywords and hooks to access EVs from S*BASIC and C68,
so the GET_ENV$ is utterly unnecessary in itself! It is also somewhat
slower than the inbuilt GETENV$ function as it first has to scan the Name
Table for the *ENV* marker, something the native version doesn't have to do
since the marker is part of its code.

GET_ENV$ can be used in the same way as GETENV$, but that is not its
purpose. The interesting bits are the library routines to scan the EV's
"database" for the key, and return a pointer to the value  of that key.

This is how ENV_BIN works:

        dc.w    1               ; one procedure
        dc.w    return-*        ; is never called!
        dc.b    5
env     dc.b    '_ENV_'         ; changed to *ENV* during initialisation
        dc.w    0               ; end procedures
        ...
        dc.w    0               ; end functions
return
        rts
*
linkd   dc.l    0               ; this will contain pointer to data
size    dc.l    0               ; size of data in bytes


The above is an excerpt of the initialisation code for ENV_BIN. On
initialisation the procedure name _ENV_ is changed to *ENV* so it cannot
be called from BASIC. (On some systems, however, this change MAY not
happen. It does, at least, on Qdos AH+ and Minerva V1.8x+, and SMSQ/E V2+)

ENV_BIN is a "systems toolkit" that must be loaded in the main BASIC. The
code is self-modifying, so is not ROMable, and should also not be included
in compiled programs but be loaded separately - preferably by your boot
program.

To get at the database you first need to find the *ENV* marker, which
is most safely done by scanning job #0's name table.

The database is just a stream of "key=value" sets, each entry terminated
by a zero byte, the way C programs like it. Ie, entries don't have the
typical word length followed by the string characters. This also means that
the entries may not start on an even address, the way Qdos and SMSQ/E like
it.

So, the way to get your EV value is:

   Scan the Name Table for the *ENV* marker
   Use the relative offset to find the start of the "procedure"
   The pointer to the database is found 2 bytes further on, and
   its size 4 bytes beyond that.

   Scan the database for your key
   When there is a mismatch, scan to the next zero byte, representing the
   end of the current record
   The database terminates on a blank record (ie two adjacent bytes of zero)
   or when the size limit has been reached.

   If the key matches to the end, and is followed by an equals sign in the
   data,
   the start of the value is found at the subsequent location
   The value string is terminated by a zero byte

Then its up to you what you want to do with it!


Program notes
=============

GET_ENV$ is basically a harness for interacting with S*BASIC. It Fetches
the key string as a parameter, looks for the EV database, scans the
database for the key, measures the length of the return value, and returns
that to S*BASIC as a normal string function.

In my ENV_GET$ routine I use a standard Name Table scanner, so it is not
optimised for this purpose. The EV scanner is case-dependent, the same as
GETENV$.


Manifest
--------

        GetEnv_txt              this text
        GET_ENV_BIN             the test toolkit containing the GET_ENV$
                                function
        GetEnv_asm              is the wrapper for the function and glues
                                the components together
        KeyG_E_asm              the keyword initialisation file
        Get_Env_link            the Qmake link file
        gtkey_asm               contains sbu_gtkey the Name Table scanner
        getenv_asm              contains ut_getenv the ENV_BIN database
                                scanner

hidden in the str_lib library are the

        gtlenc_asm              contains the C-string length counter
        ut_ucchr_asm            routine to uppercase characters, and
        ut_strequnt_asm         a routine to compare two strings, where
                                one string is of the Name Table type, ie
                                a one byte length followed by the characters

The library source files can be found at Knoware.no.


Software status
===============

V0.01, pjw, 2026 Jun 06

               Conditions of use and DISCLAIMER as per Knoware.no

Generated by QuickHTM, 2026 Jun 06