ENVIRON_DOC LAST CHANGED: 25 Apr 94

INTRODUCTION

This document discusses the topic of Environment variables in C68. It
covers how they are set up, how they are accessed, and why you might
want to use them in the first place.


WHY USE ENVIRONMENT VARIABLES

Environment Variables are an idea that has been adopted from the UNIX
operating System. Environment variables are basically global variables
that use to control certain aspects of how your system will run.
Typically you would set up standard values during the loading of your
system, although you may modify some of them at a later date.

In QDOS terms, this means that you can set up information in your BOOT
file that can be later interrogated by other programs running. This can
make it much easier to centralise the control of your system rather than
having to tell each program separately as you run it.

An important feature of Environment Variables is that they are NOT
cleared if you load a new SuperBasic program. Thus they remain set for
the duration of your session (or at least until you reset your machine).


SUPERBASIC INTERFACE

The SuperBasic interface is provided as four extensions to the
SuperBasic interpreter, the code for which in contained within the
ENV_BIN file provided with the standard C68 distribution. This file
should be LRESPR'ed if you wish to make use of the facilities that it
offers. 

The four extensions provided are as follows:- 
 
SETENV A procedure that allows you to set the value of an environment
variable 
 
ENV_LIST A procedure to list the settings of your current environment
variables to a channel (usually the screen)

ENV_DEL A procedure to delete an existing environment variable

GETENV$ A function that returns the value of a specific environment
variable. 


USING THE SUPERBASIC INTERFACE

The first thing that you are likely to want to do is to set the value of
one or more environment variables. This is done by using SuperBasic
statements of the form:

 SETENV "NAME=VALUE"

This sets up an environment variable NAME, and gives it the value VALUE.
For instance, the command
 
 SETENV "TMP=ram1_"
 
gives the environment variable TMP the value of ram1_. It is worth
noting that the VALUE part may be null, ie 
 
 SETENV "TMP=" 

will assign a null string to the variable TMP. This should be contrasted
with the putenv() usage, below as used in the C environment.

Subsequently setting another value for the same variable causes the
previous definition to be overwritten. Most users will set values at
startup from within their boot files.

You can obtain a listing of the current settings of all your Environment
Variables at any time by using a SuperBasic command of the form:

 ENV_LIST 
or
 ENV_LIST #n


This causes all currently defined environment variables to be written to
the channel specified, or #1 by default.

If you decide that you wish to completely remove an Environment
Variable, then this can be done by using a SuperBasic command of the
form: 

 ENV_DEL "NAME"

This procedure will remove an environment variable definition
completely. In many cases this will be equivalent to using the SETENV
command to give a variable a null value. They are not quite the same as
at the C level one will result in the getenv() call returning NULL, and
the other will result in it returning a pointer to a zero length string.

If you want to interrogate the value of a particular Environment
Variable from within a SuperBasic program, then this can be done by
using the function:

 GETENV$("NAME")

This allows the environment variables to be manipulated from SuperBasic.
The GETENV$ function will return the value of and environment variable,
or a null string if not found. Hence, after:

 a$="test=debug level 1"
 SETENV a$

PRINT GETENV$("test") would print the string "debug level 1"

but

PRINT GETENV$("TEST") would print a null string (since Environment
variable names are case sensitive).

and the sequence 

b$ = GETENV$("TMP")
IF b$ = "" THEN 
 b$ = "RAM1_"
 SETENV "TMP=" & b$
ENDIF
SETENV "TMP_FILE=" & b$ & "WORK_TMP"

will ensure that the TMP variable is set, and that another environmental
variable, TMP_FILE, contains a reference to a file WORK_TMP on the same
device. 


C68 C LEVEL INTERFACE

The Environment Variables capability interface is built into all C68
programs that are compiled with Release 2.01 or later of C68.

The routine main() is now passed an additional parameter at program
startup that points to the environment variables (if any) that are
currently set up. The syntax of main() is now therefore:

 int main (int argc, char * argv[], char * argp[])
 {
 ...

where the argp variable is an array of string pointers. Each entry
points to a single NULL terminated string which is in the form:

 STRING=VALUE

and the list is terminated by a NULL pointer.

A user program has a number of library routines available to manipulate
environment variables:

 - the routine getenv() can be used to obtain the value of a specific
named Environment Variable. A NULL pointer is returned if the specified
Environment Variable does not exist. i.e.
  
  getenv("TEMP");

 would return a NULL if the TEMP Environment variable did not exists,
and a pointer to its value if it did. Please note that the returned
value may also be a zero-length string for an Environment Variable that
does exist, but that has not been assigned a value. 

 - the routine putenv() can be used to give a value to an Environment
variable. This will change the value if the named Environment Variable
already exists, or create an new value if does not. Therefore a call of
the form:

  putenv("TEMP=ram1_");

 would set the environment variable TEMP to a value of ram1_.

 If you want to remove an environment variable completely then call it
assigning a zero length value. i.e.

  putenv("NAME=");

 would delete the environement variable NAME (This is a slightly
non-standard treatment).


INHERITING ENVIRONMENT VARIABLES

If a number of c68 compiled jobs are chained together then the
environment variables of each slave job are inherited from the owner.
The master job will obtain its values from the settings in SuperBasic.

This inheritance factor is important as it means that if a library call
is used to change one of the environment variables, then this is
remembered and passed on without changing the setting that is current at
the SuperBasic level.



STANDARD ENVIRONMENT VARIABLES

A number of standard Environment Variables are set up automatically by
the C68 system. These are

 PROG_USE
 DATA_USE
 SPL_USE

They contain the values for the Program, Data and Destination
directories respectively. If the program has been started from
Superbasic and these Environment Variables have not been explicitly set
at the SuperBasic level, then these Environment Variables will have the
same values as you have set up using the Toolkit 2 commands PROG_USE,
DATA_USE and SPL_USE.

TIP:  If you want your C programs to use a different default directories
to those used by Superbasic programs, then you can set any one of the
DATA_USE, PROG_USE or SPL_USE environment variablesexplicitly at the
SuperBasic levle.


WHAT PROGRAMS USE ENVIRONMENT VARIABLES

To determine whether a program will use any environment variables, it is
necessary to look at the documentation for that program.

Examples of programs that are supplied as part of the C68 system that DO
make use of Environment Variables are the CC, C68 and MAKE programs -
refer to the documentation on each program for the details.


AUTHOR(s)

Original version - Dave Nash.
C code modification - Dave Walker.
SuperBasic interface extension - Dave Woodman.


CHANGE HISTORY

This is a short summary of the changes that have been made to this
document. The intention is to make it easy for users who are upgrading
to find any new information.

25 Apr 94 DJW - Minor changes and corrections for the 4.13 release.


