home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
ftp.barnyard.co.uk
/
2015.02.ftp.barnyard.co.uk.tar
/
ftp.barnyard.co.uk
/
cpm
/
walnut-creek-CDROM
/
BEEHIVE
/
ZSUS
/
Z3HELP-6.LBR
/
ZA.LBR
/
Z3VARLIB.HZP
/
Z3VARLIB.HLP
Wrap
Text File
|
2000-06-30
|
13KB
|
326 lines
;
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