Abridged Documentation for MAKEMEM/READMEM/PARSE
24 June 1987

     This should be accompanied by MAKEMEM version 1.07, READMEM version
1.09, and PARSE version 1.05.  If you have an earlier version of MAKEMEM,
please note that this one is much faster.  This version of READMEM has more
options; so does this version of PARSE.

	 This release of the MAKEMEM/READMEM/PARSE package corrects a number
of nasty bugs found in earlier versions by Randy Wallin. 

	 Speaking of earlier versions, some of them were distributed as COM
files instead of as EXE files:  if you have one of my MAKEMEM.COM, PARSE.COM
or READMEM.COM on your machine, you should delete it if you want to try out
the new version.  (Note, however, that there is a PARSE.COM distributed by
PC Magazine which has nothing whatsoever to do with PARSE.EXE!)

	 Anyway...

     MAKEMEM and READMEM are utility programs for dBase III and dBase III
Plus.  MAKEMEM allows you to quickly import information into dBase.
READMEM reads dBase III and FoxBase+ .MEM files:  in the case of date
variables it provides more information than does dBase III itself.
PARSE is a filter that can be used with MAKEMEM or all by itself.

     Complete documentation for the programs is available to all registered
users, as is source code in C and updated versions of the programs.  You are
encouraged to register by sending $15 to the author:  Andrew Schulman,
12 Humboldt Street, Cambridge MA 02140.

     There is a good discussion of how to use MAKEMEM in Pete Olympia's
article "Extending the Power of dBase," DATA BASED ADVISOR magazine,
December 1986, pp.50-55.  (Though an improvement to PARSE has made one
example there inaccurate:  since PARSE now ignores blank lines unless told
otherwise, to extract the first file listed by DIR, use PARSE 3, not
PARSE 5.)

     All three programs are given instructions on the DOS command-line.
(They do not work interactively, as they are meant to be run under program
control.)  If you type of the name of the program without any commands (for
example, C>makemem or C>readmem or C>parse), help information will be
displayed.


     MAKEMEM
     *******

     Following are a number of contrived examples to show you how MAKEMEM
works.  You would run MAKEMEM from a dBase program rather than interactively
from the dot prompt, but this gives you a quick idea of how the program
works.

     To quickly get the volume name of the current disk into a dBase
variable:

     . run vol | makemem vol vol
     . restore from vol additive
     . ? vol
     Volume in drive D is VALDES

Notice the "additive":  this is so the variable is added to your already
existing variables rather than wiping them out!

Neither the dBase memory variable VOL nor the dBase file VOL.MEM have
to already exist.  MAKEMEM creates them:  this is one of its big advantages
over other methods of importing information into dBase, which require that
.DBF files or memory variables be set up to receive the new information.

     To get a more verbose description of the operating system than that
available with the dBase III Plus function os():

     . ! ver | makemem ver ver
     . restore from ver additive
     . ? ver
     Microsoft MS-DOS Version 3.10


     PARSE
     *****

     Unfortunately, few programs are so concise as to produce a single-line
which can be piped to MAKEMEM (the | is MS-DOS's way of piping the output
of one program into the input of another program).  You can use MAKEMEM
along with the filter program PARSE to pick the appropriate lines to be fed
to MAKEMEM.

     For example, on the last line of a DIR listing in MS-DOS, the number of
files and the bytes remaining on the disk are given.  Space remaining on the
disk is a figure available to you in dBase III Plus with the diskspace()
function, but if you want the number of files in a directory or that match a
spec:

     . run dir *.prg | parse -t -p | makemem -nprgfiles temp
     . restore from temp additive
     . ? prgfiles
     20

The -t flag told PARSE to look at the last line (tail) of its input (its
input was the listing of *.prg files).  The -p flag told PARSE to take that
line and parse it so that each word was on a separate line.  This was passed
to makemem, which put 20 into a numeric variable called PRGFILES in a
dBase file called TEMP.MEM.  The -n before the variable name told MAKEMEM to
create a numeric variable.

	 A new feature of PARSE is the -s option which allows you to search for
words and then do things to the line on which that word appears.  For example:

	 parse -sYork -a 3

would extract the third item from every line on which the word "York"
appears.  The search is case-sensitive, and is right now limited to single-
word phrases.  In future releases, I will either greater expand PARSE or
replace it with a PC port of a UNIX utility like SED or AWK.  	

     To get the date of a file into a dBase date variable:

	 . run dir debug.prg | parse 3 -p 4 | makemem -ddebugdate temp
     . restore from temp additive
     . ? debugdate
     01/02/87

If you do a DIR of a single file, the information about that file appears in
the third non-blank line.  That explains the 3 in the instruction to PARSE.
The -p, again, tells PARSE to parse the line, and the 4 following the -p
tells it we're only interested in the 4th item (the date).  We preceded the
variable name "DEBUGDATE" with a -d in the command to MAKEMEM because we
want a date variable (if we left off the -d it would have been a character
variable containing the text "1-02-87," which is not as useful as a real
date variable).

     MAKEMEM's ability to create numeric and date variables, rather than
just creating character variables and leaving it to you to convert them into
a more useable form, is one of its nicest features.


     MULTIPLE VARIABLES IN ONE PASS
     ******************************

     In all the above examples, we've just been creating one memory variable
per .MEM file.  But MAKEMEM can load a .MEM file with more than one memory
variable at a time.  In addition, we are not limited to providing input to
MAKEMEM with the DOS | pipe.  We can also use redirect text files to MAKEMEM
using DOS < redirection.

     For example (this is an extremely trivial example, but it will do),
let's say you have a text file containing these lines:

     1-3-87
     $18.57
       [ imagine blank lines here ]
     Amanda Claiborne
     William Blake's Book of Job [imagine a form feed character here ]

which I guess is some sort of bookstore invoice in a file called 87-11.INV
To create four dBase memory variables from this, of the appropriate data
type, in a file called TEMP.MEM:

     . run makemem -dinvdate -namount customer book temp < 87-11.inv
     . restore from temp additive
     . list memory
     INVDATE     pub   D  01/03/87
     AMOUNT      pub   N          18.57  (        18.57000000)
     CUSTOMER    pub   C  "Amanda Cliaborne"
     BOOK        pub   C  "William Blake's Book of Job"
     MEMERROR    pub   L  .F.
         5 variables defined,       67 bytes used
       251 variables available,   5933 bytes available

Notice that the blank lines were ignored and that the ^L form feed was
ignored.  You'll notice also there's a variable MEMERROR:  MAKEMEM always
creates this logical variable.  If everything went without a hitch, MEMERROR
will be False, but if something went wrong (for example, you asked for a
date variable but the input for it was something that couldn't possibily be
a date), then MEMERROR will be True.  Your program can check MEMERROR before
using variables created by MAKEMEM in a program:

     if memerror
        ? "Something went wrong"
     else
        ? "All's well with the world"
     endif

     Since PARSE can break up a single line into its component parts, it
is useful in creating input that MAKEMEM can turn into the different types
of memory variables:

D>dir xanadu.fox | parse 3 /p
XANADU
FOX
29271
1-15-87
3:38p

D>dir xanadu.fox | parse 3 /p | makemem file ext -nsize -ddate time temp

D>readmem temp
dBase III memory file temp.mem
FILE         Char    Pub   "XANADU"
EXT          Char    Pub   "FOX"
SIZE         Num     Pub   29271
DATE         Date    Pub   Thu 15 Jan 1987
TIME         Char    Pub   "3:38p"
MEMERROR     Logic   Pub   False
6 variables defined, 40 bytes used


     Registered users of MAKEMEM get a version of the program which will
create a very, very large number of dBase memvars (up to 235) and name them
for you too.  On the other hand, you might find my shareware program MAKEDBF
more suitable for importing large amounts of information into dBase.  If you
register you copy of MAKEMEM, I'll send you the latest copy of MAKEDBF too.


     READMEM
     *******

     Readmem simply reads dBase III .MEM files:  files created by dBase III
itself, FoxBase+, or by MAKEMEM.  You don't need dBase to examine the
contents of a .MEM file.  READMEM's output can be redirected with DOS > to a
text file, for inclusion in documentation.  Its output is more informative
than the dBase LIST MEMORY command, so you might even want to use it from
within dBase:

     . run readmem temp

     dBase III memory file temp.mem
     INVDATE    Date   Pub   Sat  3 Jan 1987
     AMOUNT     Num    Pub   18.57
     CUSTOMER   Char   Pub   "Amanda Cliaborne"
     BOOK       Char   Pub   "William Blake's Book of Job"
     MEMERROR   Logic  Pub   False
     5 variables defined, 67 bytes used

Readmem also accepts ambiguous filenames on the command line:

     readmem d:   - show all .MEM files on D: drive current directory
     readmem c:\db\*.mem - show all .MEM files in C:\DB directory
     readmem \xanadu\p* - show all P*.MEM files in current drive \xanadu dir

Readmem has command-line options for displaying date and numeric variables:

     To have numeric variables also displayed in exponential form, use the
-E option.

     To display the 8-byte IEEE number used internally by dBase to represent
all numbers, use the -I option.

     To display the Julian Period Number used internally by dBase to
maintain dates, use the -J option:

     . today = date()
     . save to temp all like today*
     . run readmem -j temp

     dBase III memory file temp.mem
     TODAY      Date   Pub   Sun  4 Jan 1987         (2446800.000000)
     1 variables defined, 9 bytes used

     To have leap years marked with an asterisk, use the -L option.

     Readmem can properly display such tricky dBase variables as the
BASEDATE, the NULL date, and the NULL number variable (the NULL number is
created if you divide by zero in dBase):

     . basedate = ctod("1/4/87") - 2446800
     . nulldate = ctod([])
     . nullnum = 5 / 0
     . save to weird
     . run readmem -j weird

     dBase III memory file weird.mem
     BASEDATE   Date   Pub   Mon  1 Jan 4713 B.C.    (0.000000)
     NULLDATE   Date   Pub   NULL DATE
     NULLNUM    Num    Pub   NULL
     3 variables defined, 27 bytes used

in contrast to dBase's own display:

     . list memory
     BASEDATE    pub   D  00/0.//.
     NULLDATE    pub   D    /  /
     NULLNUM     pub   N  ********  (*******************)
         3 variables defined,       27 bytes used
       253 variables available,   5973 bytes available

     If a character string consists entirely of spaces, READMEM will display
the dBase SPACE() function call rather than show the spaces.  For instance,
"     " will be displayed as SPACE(5).  This way you don't have to guess at
the number of spaces or laboriously count them.

     If date variables have times attached (my program MAKETIME.PRG will do
this), such date/time variables are accurately displayed by READMEM, wheras
dBase doesn't display the time portion:

     . now = ""
     . do maketime with date(),time(),now
     . ? now
     01/04/87
     . do readtime with now
     01/04/87   4:01am
     . save to temp all like now*
     . run readmem temp

     dBase III memory file temp.mem
     NOW        Date   Pub   Sun  4 Jan 1987      4:01 am
     1 variables defined, 9 bytes used

     Finally, READMEM can tell whether a .MEM file was created by dBase III
or by FoxBase+.  If the file contains FoxBase+ DIMENSION arrays, READMEM
will display them:

     D>readmem foxarray
     FoxBase memory file foxarray.mem
     FOXARRAY     Array   Pub   Dimension FOXARRAY(2,3)
      (1,1)      Char    Pub   "William Blake"
      (1,2)      Char    Pub   "Poet, Printer"
      (1,3)      Char    Pub   "Dark Satanic Mills"
      (2,1)      Char    Pub   "Fearful Symmetry"
      (2,2)      Date    Pub   Mon 28 Nov 1757
      (2,3)      Date    Pub   Sun 12 Aug 1827
     7 variables defined, 86 bytes used


     SHAREWARE!  REGISTER!
     *********************

     There are other features to these programs, but this should get you
started.

     Remember, users derive real benefits by sending the author the $15
registration fee:

     * very extensive documentation
     * source code in C
     * latest versions
     * the version of MAKEMEM that produces bushels of memory variables
	   (useful for creating on-disk arrays)
     * other dBase-related programs:  MAKEDBF, MAKEBIN, PAGES, TIME
     * helping make the Shareware experiment work

     Thank you for your support!



******************************************************************************
                        MAKEMEM REGISTRATION FORM



from: ______________________________________

      ______________________________________

      ______________________________________

      ______________________________________



date: ______________________________________


MAKEMEM 1.07
READMEM 1.09
PARSE   1.05


to:   Andrew Schulman
      12 Humboldt Street
      Cambridge MA 02140


Enclosed is a check or money order for $15 US Funds.  Please register my
copy of MAKEMEM/READMEM/PARSE and send me the latest versions, the source
code in C, and the documentation.

