ProgEnv - Program Environment Library Routines
             ==============================================
                       File: ProgEnv - Update: 1.06
                 Author: J.G.Harston - Date: 19-Apr-2020


  ProgEnv provides a function to read the program's command line parameters,
including the runpath of the program if one is available. It also provides a
procedure to call or run another program, CHAINing it if BASIC or passing it
to OSCLI if a *command, and a procedure to exit setting the program return
value.

Routine Summary
===============
  FNOS_GetEnv        - read command line and environment
PROCos()             - execute a program
PROCexit()           - exit program, setting return value

Requirements and Dependancies
=============================
  The library requires 300 free bytes above the end of the heap for
temporary storage. This memory can be overwritten after the calls. Previous
versions of the library required ctrl% and data% defined. Later versions no
longer require these.

No other libraries are required

Read Command Line
=================
DEFFNOS_GetEnv

  The function OS_GetEnv tries to read the command line used to start the
program either with a *command or by CHAINing it. Two global variable are
set: run$ to the path used to run the program and os% to the machine host
type.

OS_GetEnv must be called before the program performs any string operations
as the command line is passed via BASIC's string accumulator and any string
operations would overwrite this. String operations include manipulating
numbers as strings in any way, such as printing them.

If OS_GetEnv cannot find a startup path, then run$ will be set to "".

Examples
--------
  If the command

  *PROG one two three

is used to run the program PROG, run$ would be set to "*PROG" and the string
"one two three" would be returned. If the command:

  CHAIN "$.Mail.Sort &.In.Down"

is used, run$ would be set to "$.Mail.Sort" and the string "&.In.Down" would
be returned.

Host Values
-----------
  The global variable os% is set to a host value.

  -1 Unknown                         9 6809 system on Unix-like MOS
   0 Electron                       10 MacOS X
   1 BBC A or B                     17 6809 system on BBC-like MOS
   2 BBC B+                       
   3 BBC Master 128                 28 Commodore 64
   4 BBC Master ET                  29 TI Calculator
   5 BBC Master Compact             30 Amstrad CPC
   6 Acorn Archimedes/RISC OS       31 Sinclair Spectrum
   7 Springboard                    32 Windows/DOS PC
   8 Unix                           39 6809 system with Win/DOS-like MOS

The value in os% can be used to modify the action of the program to take
account of system dependancies, such as the different structure of pathnames
on DOS, Unix and Acorn filesystems.

Note that this value indicates the host hardware, not the BASIC language
environment. A Windows/DOS PC could be hosting ARM BASIC. A RISC OS system
could be running any of BASIC I to BASIC VI for any of a variety of CPUs. A
BBC could be running ARM BASIC V on a coprocessor.

os% forms a bitmap that indicates the host system filename structure and is
used in this way by some of the File libraries:

  000x0xxx - :d.directory.filename/ext
  000x1xxx - d:/directory/filename.ext
  nnnxxxxx - d:\directory\filename.ext

This can be tested with:

  IF (os% AND -24)=0  THEN -> :drive.directory.filename/ext
  IF (os% AND -24)=8  THEN -> drive:/directory/filename.ext
  IF (os% AND -32)<>0 THEN -> drive:\directory\filename.ext

OS_GetEnv will correctly identify the host and fetch the command line and
runpath with BBC BASIC running on:

  6502, Z80, 6809, PDP11, 68000, ARM, DOS, Windows, Brandy, Napoleon.

OS_GetEnv currently cannot correctly tell if a CP/M Z80 BASIC program is
compiled or not, so assumes it is not. It works correctly for compiled Z80
BASIC programs on Acorn platforms, and calling from the CP/M command line
with 'bbcbasic progname parameters' or from BASIC with CHAIN.

The only 68000 platform supported is the 68000 BASIC in TheEmulator which
"looks like" a 6502 environment to the running program even though the BASIC
interpeter is written in native 68000 code.

Run external program
====================
DEFPROCos(A$)

  The procedure PROCos() runs an external program. If the passed string
starts with a "*", it is passed to OSCLI and executed as a *command,
otherwise, it is CHAINed as a BASIC program. The string can include
parameters, for example:

    PROCos("Menu -return 1")
    PROCos("*Quit")

A null string is ignored, and PROCos("") just returns.

Exit current program
====================
DEFPROCexit(A%)

  This procedure exits the program, setting the program return value with
OSBYTE 1. If the global variable quit$ is set then it is passed to PROCos()
to transfer back to a calling program, which can then collect the return
value with FNosbyte(1,0,0).

Legacy issues
=============
  The functions in this library do not adhere to the name prefix naming
convention (ie LibName_FuncName). Consequently, when using this library, the
identifiers PROCos() and PROCexit() become reserved.

Version history
===============
v1.00 12-Feb-1993: Works on BBC/Arc/PC/Z80.
v1.01 09-Sep-2001: Updated for BBC BASIC for Windows.
v1.02 17-Sep-2001: Doesn't need ctrl% and data%, uses workspace at heap end.
v1.04 09-Jan-2006: Works on ARM BASIC running on the ARM CoPro.
v1.05 22-Feb-2014: Updated for BB4W v6, and Brandy Basic, non-86 emulators
                   running on Windows correctly fetch native info.
v1.06 19-Apr-2020: Updated for PDP11, Z80 with high workspace.