description.
Basic get-and-set subroutines for environment variables.

[C] functions (aka subroutines):

z_hostname()
SIGNATURE: string_o z_hostname (int *pi = NULL)
SYNOPSIS: returns the name of the current computer (host machine).
PARAMETERS

pi: [output] error indicator flag variable. possible values:
0: all ok; host name retrieved
1: error (in OS / system API level)

DESCRIPTION:
this function is simply a wrapper around the lower-layer subroutine of the same name. It provides a more convenient interface.
RETURNS: [string containing host name]: if successful; -[empty string]: if error occured.
 

z_hostid()
SIGNATURE: count_t z_hostid (int *pi, boolean unix_ut = FALSE)
SYNOPSIS: unix-centric subroutine to get the current host computer's "ID".
DESCRIPTION: this function does not work in Microsoft environments and is of dubious quality.
TRAITS:
this function is provided as-is with no warantee. It is recommended to avoid this function until after a complete restoration.
 

z_simple_runcommand()
SIGNATURE: int z_simple_runcommand (const string_o &cmd_str, flag_o &f, int *px, int *pi)
SYNOPSIS:
this runs a command as a child process, aka a sub-process. The command is provided via a string object in the parameter 'cmd_str'. The program (or calling thread) blocks until the sub-process terminates. Macros z_quick_exec() and z_bare_exec() are provided as alternate names to this subroutine - you can use any of these 3, they are exactly the same call.
This function has a number of alternative names, should you prefer them:

• z_runprog()
• z_run_program()
• z_quick_runprog()
• z_simpl_runprog()
• z_quick_exec()
• z_bare_exec()

PARAMETERS

• cmd_str: the command to run, with any additional arguments, separated by whitespace. If an argument needs to contain whitespace, it should start and end with a double-quote (see discussion above).
• f: [input] flags. default value is 0 (all bits off). bit meanings:
  0: (value = 1) if set, don't wait for the sub-program to terminate
  1: (value = 2) if set, and bit 0 is set ("no wait"), don't pause 1 second for sub-program completion
  2: (value = 4) if set, use alternate format for calling 'CreateProcess()' - entire command line with the program goes into the 2nd argument
• px: [output] the exit-return code of the program (if it was run)
• pi: [output] error indicator flag variable. possible values:
  0: all ok; program ran successfully

DESCRIPTION:
This function works in both unix and Microsoft environments. The command must provide the program name as the first "word" in 'cmd_str'. It should be the full path and file name, ie, "/var/local/mailsystem/gmail" or "c:\temp\foobar.exe". If the path to the executable contains an embedded blank, wrap the full path in double-quotes. This applies to command-line arguments, too:

int retval, ie0, ie1;
string_o s_prog = "\"C:\\Program Files\\MS Visual Studio\\VC\\bin\\";
s_prog += "cl.exe";
string_o s_exec = s_prog + "-time NOW -message \"Ouch stop!\"";
ie0 = z_bare_exec(s_exec, retval, &ie1);

Here, the sub-program's exit value is returned in 'retval', if the sub-program was successfully executed. If [for a variety of reasons] the program did not execute, -1 is returned and the value of 'retval' can be anything.
In unix OSes, the inputted string is parsed and each token fed to execvp(); this function maps onto a fork() and execvp(). In Microsoft OSs, this maps to a CreateProcess() system call.
RETURNS:
[n>=0]: the PID of the sub-process
-1: error occured (see value of "pi")
 

z_env_to_str()
SIGNATURE: string_o z_env_to_str (const string_o &nam, int *pi)
SYNOPSIS:
gets the value for a environment variable specified in 'nam'.
z_env() is an alias for this function - a [#define] macro. Thus, z_env() and z_env_to_str() are exactly identical functions.
PARAMETERS

• nam: character buffer string containing the variable name.
• pi: [output] error indicator flag variable. possible values:
  0: all ok; environment variable found & retrieved
  zErr_NotFound: environment variable not found
  zErr_Result_TooBig: value of the result [output] variable exceeds the maximum buffer size

RETURNS:
0: successful fetch
1: no such variable found in the environment
-1: error occured (see value of "pi")
 

z_setenv()
SIGNATURE: int z_setenv (const string_o &nam, const string_o &val, flag_o *pef= NULL, int *pi = NULL)
SYNOPSIS: sets (creates or updates) an environment variable. If it already exists, its value is updated. if not, it is created.
DESCRIPTION:
this function takes an optional flag parameter (implemented as a pointer to a flag object) in order to be able to control the numerous options involved with setting an environment variable in the Microsoft OS.
 

PARAMETERS

• nam: target buffer for host name
• val:
• pef:[optional] flag variable. If a flag object is provided, the following flag values (defined in z_func.h) can be set. They are all valid only under Microsoft OSes:
  zt_ENVVAR_SYS: put the environment variable in the "SYSTEM" group;
  zt_ENVVAR_USER: put the environment variable in the "USER" group;
  zt_ENVVAR_PERMANENT: make the environment variable permanent (as opposed to the current process or its children).
  zenv_NOTIFY: notify all running processes of an environment variable change.
• pi: [optional] error indicator variable. Set to non-zero if an error occurs.

RETURNS:
0: success
-1: error occured; system failure
 

history.

Sun 03/28/1999: z_hostid(): trouble with headers on solaris
Tue 10/23/2012: z_env_to_str() created
Sun 05/26/2013: Microsoft implementation of z_simple_runcommand() made