home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / jsage / zsus / z3help / y.lbr / Z3VARLIB.HZP / Z3VARLIB.HLP
Encoding:
Text File  |  1989-08-06  |  12.9 KB  |  326 lines
  1. ;
  2.                                   Z3VARLIB.REL
  3.           A Library of Assembly Routines for Handling Shell Variables
  4.      
  5.      
  6.                                I  Introduction 
  7.                                U  Memory Usage 
  8.                           F  The Shell Variable File 
  9.  
  10.                                   L  VARLOAD 
  11.                                   V  VARDEF  
  12.                                   D  DELVAR  
  13.                                   A  ADDVAR  
  14.                                   W  WRTVARS 
  15.  
  16.                     X  Dependencies Among Library Routines 
  17. :I
  18.                                  INTRODUCTION 
  19.      
  20.           Z3VARLIB.REL  consists  of  five  routines for manipulating shell
  21.      variables.    The   individual   routines   are   assembled   into   a
  22.      Microsoft-compatible  library  of  relocatable  (.REL) code fragments.
  23.      ZLINK, LINK80, and other  linkers  can  be  used  to  integrate  these
  24.      routines into your programs. 
  25.      
  26.           Z3VARLIB  provides  a  convenient  and  easy  way to create ZCPR3
  27.      utilities that can  access  shell  variables.   The  library  provides
  28.      routines  for  reading  and writing the shell variable file as well as
  29.      for finding particular shell variables and adding and  deleting  shell
  30.      variables.   Use  of  shell  variables allows a program to communicate
  31.      with other programs in a complex and detailed  fashion,  passing  both
  32.      data and status information. 
  33.  
  34.                                                                Introduction
  35.  
  36.     MODULES 
  37.  
  38.  
  39.  
  40.           The modules in the library are:
  41.  
  42.  
  43.           VARLOAD   Loads the shell variable file into memory
  44.      
  45.           VARDEF    Locates the definition for a specified variable
  46.      
  47.           DELVAR    Deletes a specified variable
  48.      
  49.           ADDVAR    Adds a new variable and definition, or redefines an old
  50.                     one
  51.      
  52.           WRTVARS   Writes out the shell variable file
  53.  
  54.                                                                Introduction
  55.  
  56.  
  57.  
  58.           A sixth PUBLIC symbol in the library is Z3VARS.  The 16-bit value
  59.      at this address is a pointer to the beginning of  the  variable  list.
  60.      Z3VARS  is  initialized by the VARLOAD routine, using the value passed
  61.      to VARLOAD in HL.  Before the variable list is loaded,  the  value  of
  62.      Z3VARS will be a binary zero. 
  63. :U
  64.                                  MEMORY USAGE 
  65.      
  66.           The  library  routines  load  the entire shell variable file into
  67.      memory and manipulate it in place.  It is expected that these routines
  68.      will be incorporated into fairly small utility  programs.   Therefore,
  69.      the  VARLOAD  routine  does  not include any checks to ensure that the
  70.      operating system is not overwritten. 
  71.      
  72.           Note that addition of a shell variable (ADDVAR) expands the space
  73.      used by the file in memory.  Redefinition may have  the  same  effect.
  74.      The  ADDVAR  also does not include any checks to avoid overwriting the
  75.      system. 
  76.      
  77.           The benefits of  this  approach  are  smaller  size  and  greater
  78.      speed.   If  the size of your program, its other dynamically allocated
  79.      data, and the shell variable file may approach the size of  your  TPA,
  80.      then  you  are  advised  to  rewrite  the  VARLOAD--and, if necessary,
  81.      ADDVAR--routines. 
  82.  
  83.                                                                Memory Usage
  84.  
  85.      
  86.           Because the memory space used may increase  when  shell  variable
  87.      definitions  are  added,  it will generally be desirable to assign the
  88.      address for the variable list after all other dynamic storage has been
  89.      allocated.  This will allow the variable list to grow upward in memory
  90.      without interference.  If you will only be locating variables (VARDEF)
  91.      or deleting variables (DELVAR), then additional dynamic storage may be
  92.      allocated immediately following the variable list. 
  93. :F
  94.                            THE SHELL VARIABLE FILE 
  95.      
  96.      FILE NAME
  97.      
  98.           If a shell variable file has been defined (i.e., if its name  has
  99.      been  loaded  into the appropriate memory buffer), these routines will
  100.      use that file.  If no alternate name has  been  defined,  the  default
  101.      name  of  SH.VAR will be used.  Note that in the second case, the name
  102.      "SH.VAR" will not be installed in  memory,  but  simply  used  by  the
  103.      library routines--the memory-based shell variable filename buffer will
  104.      remain uninitialized. 
  105.      
  106.           If  the  shell  variable  file  name  is changed between calls to
  107.      VARLOAD and WRTVARS, the variable list will be written out to the  new
  108.      name. 
  109.  
  110.                                                     The Shell Variable File
  111.  
  112.      FILE LOCATION
  113.      
  114.           These  routines  will  look  in  up  to  two places for the shell
  115.      variable file: first, in any directory named "ROOT:", if  one  exists;
  116.      if  this  directory  is  undefined,  the  routines  will  look  in the
  117.      directory at the root of the path.  If the file is not found, it  will
  118.      be created. 
  119.      
  120.           If  the  location  of  the  "ROOT:" directory (or the root of the
  121.      path, if appropriate)  is  redefined  between  calls  to  VARLOAD  and
  122.      WRTVARS, the variable list will be written out to the new location. 
  123.  
  124.                                                     The Shell Variable File
  125.  
  126.      FILE FORMAT
  127.      
  128.           Each  entry  in  the list consists of an 8-character buffer which
  129.      contains the variable name, followed by a null-terminated string which
  130.      makes up the variable definition.  If the name  is  fewer  than  eight
  131.      characters  in  length, the buffer is padded with blanks.  No explicit
  132.      delimiter separates the name and the definition. 
  133.      
  134.          The final definition in  the  file  is  followed  by  a  control-Z
  135.      character  (1A  hexadecimal,  26  decimal).  This marks the end of the
  136.      file. 
  137. :L
  138.                                    VARLOAD 
  139.      
  140.      Purpose: Load the shell variable file into memory. 
  141.      
  142.      Inputs:
  143.           HL = address of beginning of list. 
  144.      
  145.      Outputs:
  146.           if successful,
  147.                A = 00 and zero flag set (Z)
  148.                HL = next free address after variable list
  149.           if unsuccessful,
  150.                A = non-zero and zero flag reset (NZ)
  151.      
  152.      SYSLIB and Z3LIB routines called:
  153.           RETUD, LOGUD, DNSCAN, ROOT, GETFN1, INITFCB, F$OPEN, F$CLOSE
  154.  
  155.                                                                     VARLOAD
  156.  
  157.      Notes:
  158.      
  159.      1)   The address of the start of the variable list, passed in  HL,  is
  160.           stored in Z3VARS. 
  161.      
  162.      2)   The  address returned in HL, the next free memory address, may be
  163.           used for additional dynamic memory allocation,  but  addition  or
  164.           redefinition   of   variables  may  overwrite  memory  past  this
  165.           address. 
  166.      
  167.      3)   The shell variable file is looked for--or created--in the "ROOT:"
  168.           directory.  If this directory is not defined, then the  directory
  169.           at the root of the path is used. 
  170.      
  171.      4)   No  checks are performed during loading to ensure that the TPA is
  172.           large enough to hold the entire file. 
  173. :V
  174.                                     VARDEF 
  175.      
  176.      Purpose:
  177.           Locate the definition corresponding to a given variable name. 
  178.      
  179.      Inputs:
  180.           HL = address of variable name, in 8-character buffer  filled  out
  181.                with spaces. 
  182.      
  183.      Outputs:
  184.           if successful,
  185.                HL = addr of variable definition
  186.                Zero flag set (Z)
  187.      
  188.           if unsuccessful,
  189.                Zero flag reset (NZ)
  190.      
  191.      SYSLIB and Z3LIB routines called: none. 
  192.  
  193.                                                                      VARDEF
  194.  
  195.      Notes:
  196.      
  197.      1)   An  unsuccessful return may indicate either that the variable was
  198.           not found or that the shell variable file has  not  been  loaded.
  199.           Upon an unsuccessful return, the value in HL is indeterminate. 
  200.      
  201.      2)   Upon  a  successful return, HL points to the first character of a
  202.           null-terminated string which makes up the definiton. 
  203. :D
  204.                                     DELVAR 
  205.      
  206.      Purpose: Delete the variable name in the buffer pointed to by HL. 
  207.      
  208.      Inputs:
  209.           HL = address of  8-character  buffer  containing  variable  name,
  210.                blank-padded. 
  211.      
  212.      Outputs:
  213.           if successful,
  214.                A = 0 and zero flag set (Z)
  215.           if unsuccessful,
  216.                A = FF and zero flag reset (NZ)
  217.      
  218.      SYSLIB and Z3LIB routines called: none. 
  219.      
  220.      Z3VARLIB routines called: VARDEF
  221.  
  222.                                                                      DELVAR
  223.  
  224.      Notes:
  225.      
  226.      1)   A  successful return means either that the variable was found and
  227.           deleted or that the variable did not exist in  the  first  place.
  228.           In  either  case, a successful return indicates that it no longer
  229.           exists in the file. 
  230.      
  231.      2)   An unsuccessful return indicates that the shell variable file has
  232.           not been loaded. 
  233. :A
  234.                                     ADDVAR 
  235.      
  236.      Purpose: add the indicated variable name and definition to the list. 
  237.      
  238.      Inputs:
  239.           HL = address of name of variable in 8-byte buffer, blank-padded. 
  240.           DE = address of null-terminated definition string. 
  241.      
  242.      Outputs:
  243.           if successful,
  244.                A = 0 and zero flag set (Z)
  245.           if unsuccessful,
  246.                A = FF and zero flag reset (NZ)
  247.      
  248.      SYSLIB and Z3LIB routines called: none. 
  249.      
  250.      Z3VARLIB routines called: DELVAR
  251.  
  252.                                                                      ADDVAR
  253.  
  254.      Notes:
  255.      
  256.      1)   An unsuccessful return indicates that the variable  list  is  not
  257.           loaded. 
  258. :W
  259.                                    WRTVARS 
  260.      
  261.      Purpose: write the memory-based list of shell variables to disk. 
  262.      
  263.      Inputs:
  264.           none. 
  265.      
  266.      Outputs:
  267.           if successful,
  268.                A = 0 and zero flag set (Z)
  269.           if unsuccessful,
  270.                Zero flag reset (NZ)
  271.      
  272.      SYSLIB and Z3LIB routines called:
  273.           RETUD, LOGUD, INITFCB, F$DELETE, F$MAKE, F$CLOSE, DNSCAN, GETFN1,
  274.           ROOT
  275.  
  276.                                                                     WRTVARS
  277.  
  278.      Notes:
  279.      
  280.      1)   An  unsuccessful  return  may  indicate  either  that  the  shell
  281.           variable file has not been loaded or that there was a write error
  282.           (disk or directory full). 
  283.      
  284.      2)   The file will be written to the "ROOT:" directory,  or,  if  this
  285.           does not exist, to the directory at the root of the path. 
  286. :X
  287.                      DEPENDENCIES AMONG LIBRARY ROUTINES 
  288.      
  289.           Although  the  library modules are assembled separately, and need
  290.      not all be linked to a program, some of the routines call others.   In
  291.      particular,  DELVAR  calls VARDEF and ADDVAR calls DELVAR.  Thus, even
  292.      if the only library routines you explicitly use in  your  program  are
  293.      VARLOAD,  ADDVAR,  and  WRTVARS,  the  entire library will actually be
  294.      linked. 
  295.      
  296.           Some actions that you may  want  to  perform  on  or  with  shell
  297.      variables,  and the library routines that you can expect to be linked,
  298.      are listed on the next screens. 
  299.  
  300.                                         Dependencies Among Library Routines
  301.  
  302.                       Action                          Routines Linked
  303.          ==================================          =================
  304.          Perform a custom activity,  such as             VARLOAD
  305.          printing all names and definitions,
  306.          that  does not  alter the  variable
  307.          list. 
  308.      
  309.          Perform  a  custom  activity   that         VARLOAD, WRTVARS
  310.          results  in  modifications  to  the
  311.          variable list. 
  312.      
  313.          Find the definition for one or more         VARLOAD, VARDEF,
  314.          variables.                                  WRTVARS
  315.      
  316.          Delete  one  or  more  variables.           VARLOAD, VARDEF,
  317.                                                      DELVAR, WRTVARS
  318.  
  319.                                         Dependencies Among Library Routines
  320.  
  321.                       Action                          Routines Linked
  322.          ==================================          =================
  323.          Add   one  or  more  variables.             VARLOAD, VARDEF,
  324.                                                      DELVAR, ADDVAR,
  325.                                                      WRTVARS
  326.