My favorites ▼ | Sign in
Project Home Downloads Wiki Issues Source
Search
for
PJEnvVarsRoutines  
Environment Variables Unit routines.
Updated May 8, 2011 by delphidabbler

Environment Variables Routines

Project: Environment Variables Unit.

Unit: PJEnvVars.

The following public routines are defined in PJEnvVars:

GetEnvVarValue

function GetEnvVarValue(const VarName: string): string;

Returns the value of the environment variable named by VarName. The empty string is returned if the named variable does not exist.

SetEnvVarValue

function SetEnvVarValue(const VarName, VarValue: string): Integer;

Sets the environment variable named by VarName to VarValue. If there is no usch environment variable it is created. If VarValue is the empty string then the environment variable is deleted.

Returns 0 on success or a Windows error code on error. The most likely cause of error is that the environment block is full and there is no room for the new value or to create a new variable. A description of any error can be found by passing the error code to SysUtils.SysErrorMessage.

NOTE: This routine does not update the system's environment variables, only the copy of the environment maintained by this program.

DeleteEnvVar

function DeleteEnvVar(const VarName: string): Integer;

Deletes the environment variable specified by VarName. If the variable does not exist DeleteEnvVar does nothing.

If DeleteEnvVar completes successfuly then 0 is returned. If an error occurs then a non-zero Windows error code is returned. A description of any error can be found by passing the error code to SysUtils.SysErrorMessage.

NOTE: This routine has no effect on the system's environment variables, only the copy of the environment maintained by this program.

GetAllEnvVars

function GetAllEnvVars(const Vars: TStrings): Integer;

Copies all the environment variables available to the current process in to the given string list. Each item placed in the string list represents one environment variable in the form NAME=VALUE. Any previous contents of the string list are lost.

The size of the environment block in characters is returned.

It is permitted to pass nil as the parameter to GetAllEnvVars. If this is done then details of the environment variables are not provided, but the size of the environment block is returned. Therefore this function can also be used to determine the size of the environment block.

WARNING: The size of the environment block is returned in characters, not bytes. Therefore, you should multiply the required buffer size by SizeOf(Char) to determine the number of bytes required.

ExpandEnvVars

function ExpandEnvVars(const Str: string): string;

ExpandEnvVars replaces any environment variables embedded in string Str with their values and returns the modified string.

Environment variables should be delimited by % characters thus: %ENVVAR%. If any environment variables are not recognised their names are left unmodified. The case of the environment variable name is not significant: i.e. %ENVVAR% is the same as %envvar%.

CreateEnvBlock

function CreateEnvBlock(const NewEnv: TStrings;
  const IncludeCurrent: Boolean; const Buffer: Pointer;
  const BufSize: Integer): Integer;

CreateEnvBlock creates a new environment block that can be used to pass to another process.

The new environment block is stored in the memory pointed to by Buffer, which is taken to be at least BufSize characters in size. The actual size of the environment block is returned by CreateEnvBlock. If the buffer provided is nil or is too small then no block is created and the return value is the required buffer size in characters.

The NewEnv and IncludeCurrent parameters determine what is included in the new environment block. If the NewEnv string list is not nil then it must contain a list of environment variables in the form NAME=VALUE. The new environment block will contain these values. If IncludeCurrent is true then the new environment block will also include a copy of the current process' environment block.

The usual way to use CreateEnvBlock is to call it once with a nil buffer to get the required buffer size in characters, allocate the buffer and then call CreateEnvBlock again, this time passing the actual buffer and its size, for example: 

var
  EnvBlock: Pointer;
  BlockSize: Integer;
  NewEnv: TStringList;
begin
  // Create and populate NewEnv
  // ...
  // Create the environment block: include NewEnv and process' own block
  BlockSize := CreateEnvBlock(NewEnv, True, nil, 0);
  // BlockSize is in Characters, not bytes: so needs converting to bytes
  GetMem(EnvBlock, BlockSize * SizeOf(Char));
  try
    CreateEnvBlock(NewEnv, True, EnvBlock, BlockSize);
    // Execute a program with environment block
    // ...
  finally
    FreeMem(EnvBlock);
  end;
end;

WARNING: CreateEnvBlock deals with buffer sizes in characters, not bytes, which is not the same thing on Unicode Delphis. When allocating buffers in bytes (e.g. with GetMem) you must multiply the required size returned from CreateEnvBlock by SizeOf(Char). Alternatively, use a routine such as StrAlloc that automatically takes account of the character size.

The format of the environment block stored in Buffer is a #0 character separated list of environment variables in NAME=VALUE form, terminated by two #0 characters.

GetAllEnvVarNames

procedure GetAllEnvVarNames(const Names: TStrings); overload;
function GetAllEnvVarNames: TStringDynArray; overload;

Both overloaded versions of this routine fetch a list of the current environment variable names. Any blank names are excluded from the list.

The first version of the routine stores the environment variable names in the Names string list. Any existing contents of the string list are discarded.

The second version creates and returns a dynamic string array containing the environment variable names. TStringDynArray is defined in the Types unit. If the version of Delphi being used does not have the Types unit then TStringDynArray is defined in PJEnvVars.

EnvBlockSize

function EnvBlockSize: Integer;

This function returns the size of the current environment block in characters. To get the size in bytes multiply the returned value by SizeOf(Char).


► Sign in to add a comment
Powered by Google Project Hosting