;
                                  Z3VARLIB.REL
          A Library of Assembly Routines for Handling Shell Variables
     
     
                                I  Introduction
                                U  Memory Usage
                           F  The Shell Variable File
 
                                   L  VARLOAD
                                   V  VARDEF
                                   D  DELVAR
                                   A  ADDVAR
                                   W  WRTVARS

                     X  Dependencies Among Library Routines
:I
                                  INTRODUCTION
     
          Z3VARLIB.REL  consists  of  five  routines for manipulating shell
     variables.    The   individual   routines   are   assembled   into   a
     Microsoft-compatible  library  of  relocatable  (.REL) code fragments.
     ZLINK, LINK80, and other  linkers  can  be  used  to  integrate  these
     routines into your programs. 
     
          Z3VARLIB  provides  a  convenient  and  easy  way to create ZCPR3
     utilities that can  access  shell  variables.   The  library  provides
     routines  for  reading  and writing the shell variable file as well as
     for finding particular shell variables and adding and  deleting  shell
     variables.   Use  of  shell  variables allows a program to communicate
     with other programs in a complex and detailed  fashion,  passing  both
     data and status information. 

                                                               Introduction

     MODULES



          The modules in the library are:


          VARLOAD   Loads the shell variable file into memory
     
          VARDEF    Locates the definition for a specified variable
     
          DELVAR    Deletes a specified variable
     
          ADDVAR    Adds a new variable and definition, or redefines an old
                    one
     
          WRTVARS   Writes out the shell variable file

                                                               Introduction



          A sixth PUBLIC symbol in the library is Z3VARS.  The 16-bit value
     at this address is a pointer to the beginning of  the  variable  list.
     Z3VARS  is  initialized by the VARLOAD routine, using the value passed
     to VARLOAD in HL.  Before the variable list is loaded,  the  value  of
     Z3VARS will be a binary zero. 
:U
                                  MEMORY USAGE
     
          The  library  routines  load  the entire shell variable file into
     memory and manipulate it in place.  It is expected that these routines
     will be incorporated into fairly small utility  programs.   Therefore,
     the  VARLOAD  routine  does  not include any checks to ensure that the
     operating system is not overwritten. 
     
          Note that addition of a shell variable (ADDVAR) expands the space
     used by the file in memory.  Redefinition may have  the  same  effect.
     The  ADDVAR  also does not include any checks to avoid overwriting the
     system. 
     
          The benefits of  this  approach  are  smaller  size  and  greater
     speed.   If  the size of your program, its other dynamically allocated
     data, and the shell variable file may approach the size of  your  TPA,
     then  you  are  advised  to  rewrite  the  VARLOAD--and, if necessary,
     ADDVAR--routines. 

                                                               Memory Usage

     
          Because the memory space used may increase  when  shell  variable
     definitions  are  added,  it will generally be desirable to assign the
     address for the variable list after all other dynamic storage has been
     allocated.  This will allow the variable list to grow upward in memory
     without interference.  If you will only be locating variables (VARDEF)
     or deleting variables (DELVAR), then additional dynamic storage may be
     allocated immediately following the variable list. 
:F
                            THE SHELL VARIABLE FILE
     
     FILE NAME
     
          If a shell variable file has been defined (i.e., if its name  has
     been  loaded  into the appropriate memory buffer), these routines will
     use that file.  If no alternate name has  been  defined,  the  default
     name  of  SH.VAR will be used.  Note that in the second case, the name
     "SH.VAR" will not be installed in  memory,  but  simply  used  by  the
     library routines--the memory-based shell variable filename buffer will
     remain uninitialized. 
     
          If  the  shell  variable  file  name  is changed between calls to
     VARLOAD and WRTVARS, the variable list will be written out to the  new
     name. 

                                                    The Shell Variable File

     FILE LOCATION
     
          These  routines  will  look  in  up  to  two places for the shell
     variable file: first, in any directory named "ROOT:", if  one  exists;
     if  this  directory  is  undefined,  the  routines  will  look  in the
     directory at the root of the path.  If the file is not found, it  will
     be created. 
     
          If  the  location  of  the  "ROOT:" directory (or the root of the
     path, if appropriate)  is  redefined  between  calls  to  VARLOAD  and
     WRTVARS, the variable list will be written out to the new location. 

                                                    The Shell Variable File

     FILE FORMAT
     
          Each  entry  in  the list consists of an 8-character buffer which
     contains the variable name, followed by a null-terminated string which
     makes up the variable definition.  If the name  is  fewer  than  eight
     characters  in  length, the buffer is padded with blanks.  No explicit
     delimiter separates the name and the definition. 
     
         The final definition in  the  file  is  followed  by  a  control-Z
     character  (1A  hexadecimal,  26  decimal).  This marks the end of the
     file. 
:L
                                    VARLOAD
     
     Purpose: Load the shell variable file into memory. 
     
     Inputs:
          HL = address of beginning of list. 
     
     Outputs:
          if successful,
               A = 00 and zero flag set (Z)
               HL = next free address after variable list
          if unsuccessful,
               A = non-zero and zero flag reset (NZ)
     
     SYSLIB and Z3LIB routines called:
          RETUD, LOGUD, DNSCAN, ROOT, GETFN1, INITFCB, F$OPEN, F$CLOSE

                                                                    VARLOAD

     Notes:
     
     1)   The address of the start of the variable list, passed in  HL,  is
          stored in Z3VARS. 
     
     2)   The  address returned in HL, the next free memory address, may be
          used for additional dynamic memory allocation,  but  addition  or
          redefinition   of   variables  may  overwrite  memory  past  this
          address. 
     
     3)   The shell variable file is looked for--or created--in the "ROOT:"
          directory.  If this directory is not defined, then the  directory
          at the root of the path is used. 
     
     4)   No  checks are performed during loading to ensure that the TPA is
          large enough to hold the entire file. 
:V
                                     VARDEF
     
     Purpose:
          Locate the definition corresponding to a given variable name. 
     
     Inputs:
          HL = address of variable name, in 8-character buffer  filled  out
               with spaces. 
     
     Outputs:
          if successful,
               HL = addr of variable definition
               Zero flag set (Z)
     
          if unsuccessful,
               Zero flag reset (NZ)
     
     SYSLIB and Z3LIB routines called: none. 

                                                                     VARDEF

     Notes:
     
     1)   An  unsuccessful return may indicate either that the variable was
          not found or that the shell variable file has  not  been  loaded.
          Upon an unsuccessful return, the value in HL is indeterminate. 
     
     2)   Upon  a  successful return, HL points to the first character of a
          null-terminated string which makes up the definiton. 
:D
                                     DELVAR
     
     Purpose: Delete the variable name in the buffer pointed to by HL. 
     
     Inputs:
          HL = address of  8-character  buffer  containing  variable  name,
               blank-padded. 
     
     Outputs:
          if successful,
               A = 0 and zero flag set (Z)
          if unsuccessful,
               A = FF and zero flag reset (NZ)
     
     SYSLIB and Z3LIB routines called: none. 
     
     Z3VARLIB routines called: VARDEF

                                                                     DELVAR

     Notes:
     
     1)   A  successful return means either that the variable was found and
          deleted or that the variable did not exist in  the  first  place.
          In  either  case, a successful return indicates that it no longer
          exists in the file. 
     
     2)   An unsuccessful return indicates that the shell variable file has
          not been loaded. 
:A
                                     ADDVAR
     
     Purpose: add the indicated variable name and definition to the list. 
     
     Inputs:
          HL = address of name of variable in 8-byte buffer, blank-padded. 
          DE = address of null-terminated definition string. 
     
     Outputs:
          if successful,
               A = 0 and zero flag set (Z)
          if unsuccessful,
               A = FF and zero flag reset (NZ)
     
     SYSLIB and Z3LIB routines called: none. 
     
     Z3VARLIB routines called: DELVAR

                                                                     ADDVAR

     Notes:
     
     1)   An unsuccessful return indicates that the variable  list  is  not
          loaded. 
:W
                                    WRTVARS
     
     Purpose: write the memory-based list of shell variables to disk. 
     
     Inputs:
          none. 
     
     Outputs:
          if successful,
               A = 0 and zero flag set (Z)
          if unsuccessful,
               Zero flag reset (NZ)
     
     SYSLIB and Z3LIB routines called:
          RETUD, LOGUD, INITFCB, F$DELETE, F$MAKE, F$CLOSE, DNSCAN, GETFN1,
          ROOT

                                                                    WRTVARS

     Notes:
     
     1)   An  unsuccessful  return  may  indicate  either  that  the  shell
          variable file has not been loaded or that there was a write error
          (disk or directory full). 
     
     2)   The file will be written to the "ROOT:" directory,  or,  if  this
          does not exist, to the directory at the root of the path. 
:X
                      DEPENDENCIES AMONG LIBRARY ROUTINES
     
          Although  the  library modules are assembled separately, and need
     not all be linked to a program, some of the routines call others.   In
     particular,  DELVAR  calls VARDEF and ADDVAR calls DELVAR.  Thus, even
     if the only library routines you explicitly use in  your  program  are
     VARLOAD,  ADDVAR,  and  WRTVARS,  the  entire library will actually be
     linked. 
     
          Some actions that you may  want  to  perform  on  or  with  shell
     variables,  and the library routines that you can expect to be linked,
     are listed on the next screens. 

                                        Dependencies Among Library Routines

                      Action                          Routines Linked
         ==================================          =================
         Perform a custom activity,  such as             VARLOAD
         printing all names and definitions,
         that  does not  alter the  variable
         list. 
     
         Perform  a  custom  activity   that         VARLOAD, WRTVARS
         results  in  modifications  to  the
         variable list. 
     
         Find the definition for one or more         VARLOAD, VARDEF,
         variables.                                  WRTVARS
     
         Delete  one  or  more  variables.           VARLOAD, VARDEF,
                                                     DELVAR, WRTVARS

                                        Dependencies Among Library Routines

                      Action                          Routines Linked
         ==================================          =================
         Add   one  or  more  variables.             VARLOAD, VARDEF,
                                                     DELVAR, ADDVAR,
                                                     WRTVARS
