ProgEnv - Program Environment Library Routines
	     ==============================================
		       File: ProgEnv - Update: 1.04
		 Author: J.G.Harston - Date: 09-Jan-2007


  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 270 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.  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			6 Acorn Archimedes/RISC OS PC
 0 Electron			7 Springboard
 1 BBC A or B			8 Unix
 2 BBC B+ 
 3 BBC Master 128		30 Amstrad CPC
 4 BBC Master ET 		31 Sinclair Spectrum
 5 BBC Master Compact		32 Windows/DOS PC

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 indicates the host hardware, not the BASIC language
environment. A Windows/DOS PC could be running BASIC IV or BASIC V.  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.


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 12Feb1993: Works on BBC/Arc/PC/Z80.
v1.01 09Sep2001: Updated for BBC BASIC V for Windows.
v1.02 17Sep2001: Doesn't need ctrl% and data%, uses workspace at heap end.
v1.04 09Jan2006: Works on ARM BASIC running on the ARM CoPro.