acp_env.c

   File         : acp_env.c
   Description  : Active C Page Environment Structure
   Category     : ACP Scripting
   Author       : Charles Yates
  
   This structure is used to propogate collections of name/value pairs around
   the system. 

   ACPENV DLLEXP ACPENV_Init()
 
   Function     : ACPENV_Init
   Description  : Creates an active c page environment
   Input        : void
   Output       : void
   Returns      : ACPENV - an empty acp environment

   void DLLEXP ACPENV_AllowDuplicates( ACPENV env )
 
   Function     : ACPENV_AllowDuplicates
   Description  : Informs subsequent calls to set to store duplicate names.
   Input        : ACPENV env - environment to modify
   Output       : env is updated to accept duplicates
   Returns      : void
   Special Logic: Care should be taken with subsequent calls to ACPENV_Get as
                  it will only locate the first name.  This step is not
                  reversible.

   ACPENV DLLEXP ACPENV_Params( char *string )
 
   Function     : ACPENV_Params
   Description  : Creates a environment containing split up url paramaters
   Input        : char *string - string containing url paramaters
   Output       : void
   Returns      : ACPENV - a populated acp environment (duplicates allowed)

   char *ACPENV_ExpandValue( ACPENV env, char *newValue, char *value )
 
   Function     : ACPENV_ExpandValue
   Description  : Expands a value according to the rules below.
   Input        : ACPENV env - environment which the expansion is relative to
                  char *newValue - storage for the returned value
                  char *value - value to be expanded
   Output       : newvalue contains the expanded value
   Returns      : The address of newValue
   Special Logic:
  
   The value contains strings of the form "*%%key%%*" or "~*" or just "*" where
   * is any set of characters. When %%key%% is found, 'key' is located in the
   given environment and put in place. If key does not exist, it is replaced by
   an empty string. ~ maps to the current users home directory. Other values 
   (not containing either of these cases) are returned as is.
  
   Note:
  
   1) this function can lead to buffer overruns so use with care
   2) Only one key OR ~ is expanded in a single call

   int DLLEXP ACPENV_Load( ACPENV env, char *file )
 
   Function     : ACPENV_Load
   Description  : Loads the contents of property file into the env
   Input        : ACPENV env - environment to update
                  char *file - file to load from
   Output       : env is updated to include contents of file
   Returns      : int - 0 is successful

   int DLLEXP ACPENV_Save( ACPENV env, char *file )
 
   Function     : ACPENV_Save
   Description  : Saves the contents of the env to property file
   Input        : ACPENV env - environment to update
                  char *file - file to load from
   Output       : file is written with contents of env
   Returns      : int - 0 is successful

   int DLLEXP ACPENV_Set( ACPENV env, char *name, char *value )
 
   Function     : ACPENV_Set
   Description  : Appends or updates the name=value pair in the environment
   Input        : ACPENV env - environment to update
                  char *name - property name
                  char *value - property value
   Output       : void
   Returns      : int - 0 is success, <> 0 is failure

   int DLLEXP ACPENV_Count( ACPENV env )
 
   Function     : ACPENV_Count
   Description  : Returns the number of name/value pairs in the environment
   Input        : ACPENV env - environment to query
   Output       : void
   Returns      : int - number of name value pairs

   char * DLLEXP ACPENV_Get( ACPENV env, char *name )
 
   Function     : ACPENV_Get
   Description  : Returns value associated to name
   Input        : ACPENV env - environment to query
                  char *name - name of property
   Output       : void
   Returns      : char * - address of value

   char * DLLEXP ACPENV_GetName( ACPENV env, int index )
 
   Function     : ACPENV_GetName
   Description  : Gets name at index
   Input        : ACPENV env - environment to query
                  int index - index to query
   Output       : void
   Returns      : char * - address of name at index [or NULL if not found]

   char * DLLEXP ACPENV_GetValue( ACPENV env, int index )
 
   Function     : ACPENV_GetValue
   Description  : Gets value at index
   Input        : ACPENV env - environment to query
                  int index - index to query
   Output       : void
   Returns      : char * - address of value at index [or NULL if not found]

   char * DLLEXP ACPENV_GetOrDefault( ACPENV env, char *name, char *value )
 
   Function     : ACPENV_GetOrDefault
   Description  : Gets value by name or returns default
   Input        : ACPENV env - environment to query
                  char *name - name of entry
                  char *value - default value if not existing
   Output       : void
   Returns      : derived value

   int DLLEXP ACPENV_GetOrDefaultInt( ACPENV env, char *name, int value )
 
   Function     : ACPENV_GetOrDefaultInt
   Description  : Gets value by name or returns default
   Input        : ACPENV env - environment to query
                  char *name - name of entry
                  int value - default value if not existing
   Output       : void
   Returns      : derived value

   int DLLEXP ACPENV_Find( ACPENV env, char *name )
 
   Function     : ACPENV_Find
   Description  : Retrns the index containing name
   Input        : ACPENV env - environment to query
                  char *name - name to find
   Output       : void
   Returns      : int - location of name in the environment

   void DLLEXP ACPENV_Close( ACPENV env )
 
   Function     : ACPENV_Close
   Description  : Closes the environment
   Input        : ACPENV env - environment to close
   Output       : env is closed
   Returns      : void