Shareware Overload/ShartewareOverload.cdr/database/wp_dbase.zip/WPMERGE.DOC

Text File | 1986-09-05 | 16KB | 378 lines

                              WPMERGE

Version 1.0
October 1986

********************************************************************
* Copyright 1986 by    Stuart Ozer                                 *
*                      Cursor Left Software                        *
*                      182 East 7th Street, #3-S                   *
*                      New York, NY  10009                         *
*                                                                  *
*   USER-SUPPORTED SOFTWARE.  Please copy and distribute this      *
*   program!  If you find this product useful, please send $25     *
*   (checks only, please, payable to Stuart Ozer) to the address   *
*   above.  You will be notified of future Dbase III Plus          *
*   utilities and receive support and upgrade announcements        *
*   for this product.                                              *
*                                                                  *
*   Your comments and suggestions are appreciated!                 *
*                                                                  *
********************************************************************

   A utility program running under Dbase III Plus to convert
   Dbase data into WordPerfect format for mail-merge
   applications.

   Features:

   * Emulates DBASE Label Form system to define output data
   * Menu-driven, with help.
   * Can output data from multiple related DBASE fields into one
     WordPerfect merge file.
   * Can create multiple line WordPerfect fields, with blank
     lines suppressed.
   * Creates custom DBASE programs to output particular merge
     files.  You can incorporate these programs into your own
     applications.
   * Saves merge file definitions for future use or modification.
   * Output is WordPerfect ready.  No additional conversion is
     needed.


1.  CONTENTS & INSTALLATION

    The complete WPMERGE package includes the following files:

    WPMERGE.PRG  (The DBASE program file)
    WPMERGE.DEF  (A necessary definition file)
    WPMERGE.DOC  (This document)

    Place WPMERGE.PRG and WPMERGE.DEF in your Dbase III+ directory.

    Since you will probably want to use WPMERGE when working in
    another directory, be sure that you have a file CONFIG.DB in
    your DBASE III+ directory, and that it contains the command:

             PATH=<directory list>

    with the DBASE III+ directory included in <directory list>.  See
    your DBASE manual for details on the CONFIG.DB file.


2.  HOW WPMERGE WORKS

    WPMERGE expects you to have DBASE files already filled with data
    to convert into WordPerfect format.  WPMERGE will not disturb
    data in existing files, but will write new data files that can be
    used with your word processor.

    WPMERGE will create the following types of files:

    <filename>.SF   --  Data file compatible with WordPerfect merge
                        format.  ('SF' stands for Secondary File in
                        WordPerfect lingo.)

    <filename>.WPM  --  Saved definitions for a creating a
                        particular WordPerfect merge file.   WPMERGE
                        remembers previous merge formats you've
                        designed. (These are analogous to .LBL files
                        which define a label format in DBASE.)

    <filename>.PRG  --  WPMERGE writes a DBASE III + program for
                        each particular merge file you define, and
                        gives you the option of naming and saving
                        the program.  This program can be run to
                        create a merge file in the future without
                        using WPMERGE by typing  DO <filename>.  You
                        can also incorporate the .PRG program into
                        other programs of your own.


    DBASE and WordPerfect maintain data in different formats.  Here
    are the main differences, and what WPMERGE does about them:

    A.  Dbase fields have a fixed length.  WordPerfect fields
        have variable length.  So WPMERGE trims trailing blanks.

        Suppose you want to merge a first name into a letter.  A
        line in your letter might be:

                     Dear ^F2^,

        Where ^F2^ is the WordPerfect merge code for the first data
        field (in this case containing first name).  Each first name
        in the DBASE file probably includes several blank spaces at
        the end. This would be a disaster in WordPerfect, because
        the comma after Dear <name> would then be separated from the
        name.

        To prevent this problem, WPMERGE automatically TRIMS
        trailing blanks from each line in the resulting WordPerfect
        merge file.

    B.  WordPerfect allows fields that take up more than one line,
        unlike DBASE.  So WPMERGE allows you to construct multiple-
        line fields, and suppresses blank lines.

        In Wordperfect, a complete address block can be treated as
        one field.  For example, a letter heading in WordPerfect
        might look like:

             January 15, 1987

             ^F1^

             Dear ^F2^,

        Here, ^F1^ is the merge code for a multiple-line name and
        address block.  Some addresses might have a "care-of" line
        or other optional address, other may not.  So ^F1^ may have
        a variable number of lines.  WPMERGE allows you to define
        multiple-line WordPerfect merge fields, and automatically
        eliminates blank lines in the middle of a multiple-line
        WordPerfect field.


3.  START WPMERGE

    Set up your work areas as though you were about to generate
    labels -- i.e. USE one or more files of your choice, along with
    any needed index;  SET FILTER to any filter condition you wish,
    and SET RELATION if you wish to access data from more than one
    database in use.

    If you are using multiple files, be sure that your primary data
    file is in work area 1.  In addition, work are 9 is reserved for
    WPMERGE, so leave it empty.

    We suggest that you start WPMERGE from the directory containing
    your DBASE file.  When your files are set up as you wish, type:

            DO WPMERGE

    You may abort WPMERGE at any time by typing the <esc> key,  No
    files will be damaged.  Simply answer "Y" to the Cancel? prompt.

    After you start WPMERGE, the name of the primary file in use (the
    file in work area 1) will be displayed, and WPMERGE will ask you
    to verify it is correct.

4.  NAME A MERGE DEFINITION FILE

    WPMERGE will display a list of .WPM files in your current
    directory.  These contain information about previous merge files
    you've defined using WPMERGE.  To perform a previously defined
    merge file creation, or edit a definition, type one of the
    names (if any) displayed on the screen.  Enter the first name
    only, not ".WPM".

    If you want to define a new merge file, enter a new name, and
    confirm by typing "Y" at the NEW DEFINITION? prompt.

    (NOTE:  WPMERGE will not permit you to give a merge definition the
    same first name as a DBASE file in use.)

    If you are re-creating a previously defined merge file, WPMERGE
    will give you the option of bypassing the definition display /
    edit screen described below.


5.  CREATE / EDIT A MERGE FILE DEFINITION

    The bottom two lines of the screen will always display the
    keyboard options available to you at any point.

    Initially, the top portion of the screen will display the first
    20 field names and types (Character, Numeric, Logical, Date or
    Memo) available in the primary database.

    Use the HELP  (<control><home>) command, and help option 1, to
    obtain a list of all field names in all open files.

    HELP also provides a brief summary how to use WPMERGE.

    The middle part of the screen is the main work area.  It lets
    you enter the DBASE expressions for the contents of every line
    to be sent to a WordPerfect merge file.

    The left column displays the line number of each line in the
    merge file being defined.  The WordPerfect merge file you define
    may contain an unlimited number of fields for each record.

    Use <up-arrow> and <down-arrow> to move the curser to any line
    of the definition screen, and hit <return> to enter data on the
    line you are pointing to.

    In the highlighted area labelled CONTENTS OF LINE, type the
    DBASE expression for the line.  For example, for a DBASE file
    containing City, State and Zip fields, the last line of a
    WordPerfect address field would be defined as:

            trim(city) + ", " + state + "   " + zip

    The contents of each line must be a character expression.
    WPMERGE will check the validity of what you type, and force you
    to reenter any bad definition or non-character expression.  To
    insert numeric or date data, you must use the conversion
    functions STR() or DTOC() respectively.  Memo fields won't work.

    You may include data from other related files in use by using
    the relational operator ( -> ) in line expressions, just as you
    would in report or label forms:

            <alias name> -> <related file field name>.

    After entering the contents of a line, you must tell WPMERGE
    whether or not that is the end of a WordPerfect merge field.  If
    you wish to enter more lines for a multi-line field, enter 'N'
    for END OF WP FIELD?  If you are done, or if the next line you
    wish to define starts a NEW field in WordPerfect, answer 'Y'
    here.

    Just as in the CREATE LABEL command, WPMERGE expects to move
    the cursor up or down after entering each line, and then to hit
    <return> to enter information on a line you are pointing to.

    If your merge file definition is more than 12 lines long,
    WPMERGE will present you with a fresh screen to work on if you
    move the cursor <down-arrow> after the 12th line.

    When you are done defining all lines, type <end> or <page-down>.


7.  CREATING THE MERGE DATA FILE

    You will be asked to name a new WordPerfect Merge Data File to
    store your DBASE data in WordPerfect format:

      Enter a name (or path) for WordPerfect Merge Data File: <name>.SF

    The filename automatically includes ".SF" as its extension (or
    second name). ".SF" stands for Secondary File in WordPerfect
    lingo.  If the full name (including path) takes up more space
    than is displayed, the name will scroll.  If you do not include
    a path, the file will be saved in the current directory.  Do
    not type the extension ".SF", it is automatically included in
    the name.

    If a WordPerfect data file of the same name already exists, you
    will be warned and asked to confirm the name.    WPMERGE then
    creates a small DBASE III + program to perform the actual
    conversion from DBASE to WordPerfect of the particular file and
    merge structure you are working with.

    You are now given the chance to permanently save the program
    which WPMERGE writes:

         Do you want to save the merge program? [Y/N]  <y/n>

    Answering [Y]es will allow you to produce an identically defined
    merge file in the future WITHOUT using WPMERGE.  If you answer
    [N]o, WPMERGE will STILL remember how you created this
    particular merge file, and you will be able to repeat the same
    process in the future.  The only difference is that you will
    have to use WPMERGE to retrieve the merge file definition you've
    created, rather than run the stand-alone DBASE program which
    WPMERGE has just created.

    If you are developing a DBASE III + application, you may wish to
    save the program DBASE writes.  You can then incorporate it in
    your system to perform the particular data translation you've
    defined.

    Before performing the actual merge file creation, WPMERGE asks
    you again if you wish to proceed:

         Create WordPerfect Merge Data File? [Y/N]  <y/n>

    Answering [N]o at this point avoids building the actual
    WordPerfect file, while still preserving the merge file
    definition and the DBASE program to perform the merge in the
    future.  Answering [Y]es proceeds with constructing the
    WordPerfect file.

    As the WordPerfect data file is being creating, a message
    displays the number of records which have been converted.   The
    process is not fast on a PC, but no other conversion method is
    quicker or more straightforward.

    During WordPerfect Merge File Creation, hitting <esc> will allow
    you to abort the process.

8.  TO RUN A SAVED PROGRAM

    Open all necessary data and index files.  Set filters and
    relations as needed.  Then type

                          DO <filename>

    where <filename> is the name of a previously saved merge file
    creation program.  The program may be incorporated into other
    DBASE programs which you write.

9.  EXAMPLES


    EXAMPLE 1:

         Your DBASE file contains fields FIRSTNAME, LASTNAME,
         SALUTATION, COMPANY, OPTIONAL, STREET, CITY, STATE, ZIP,
         PROD_CODE

         Where SALUTATION contains "Ms.","Mr.", or "Dr."  and
         PROD_CODE contains a code for product "V" for Vacuum
         Cleaner or "C" for Computer

         You want to create a WordPerfect Merge file containing an
         ^F1^ = Address Block
         ^F2^ = Full Salutation  (i.e. "Ms. Smith")

          The merge file definition will look like this:


       Contents of merge data file (by line):            End of WP field?
  1    trim(salutation)+" "+trim(firstname)+" " +lastname       N
  2    company                                                  N
  3    optional                                                 N
  4    street                                                   N
  5    trim(city)+", "+state+"  "+zip                           Y
  6    trim(salutation)+" "+lastname                            Y

         The first five lines define the address block field, line 6
         is the full salutation.  Blank lines will be suppressed in
         the WordPerfect file -- some addresses will have 4 lines,
         others will have 5.

    EXAMPLE 2:

    In the example above, the DBASE file includes a product code.
    WPMERGE cannot substitute a full product name for a code, but
    WordPerfect certainly can.

    So, if you wanted to make reference to the coded product in your
    personalized letter, include the product code and a "tagword" in
    your merge file definition.  Then, in WordPerfect, search-and-
    replace the tagword-code combination with the full product name.
    In the example above, add a line 7 in the merge definition:

        7    "product:"+prod_code                          Y

    The text "product:" serves as the tagword, and will be followed
    immediately by the product code in the merge file.

    After WPMERGE creates the merge file, call it up in WordPerfect
    and perform a search & replace <alt>-F2 :

        srch->: product:V
        replace with: Vacuum Cleaner

        srch->: product:C
        replace with: Computer

     The merge file now contains the full text of your product name
     in each record.  So, performing a Wordperfect merge now will
     insert the full name for the products into your letters.