RISC DISC 1/RISC_DISC_1.iso/pd_share/apps/powerbase/Docs/MailMerge

Text File | 1994-10-01 | 12.1 KB | 268 lines

                Mail-merging with Impression and Ovation
                ========================================

Although we have called this file ‘MailMerge’ the process to be described is
more accurately termed “data-merge” since it is by no means limited to
merging names and addresses into letters: any kind of textual data from a
Powerbase application can be merged into any kind of Impression or Ovation
document.

Mail-merging with Ovation
=========================
Ovation expects data for merging to be supplied as a CSV (comma-separated
value) file. An example file (‘OvationCSV’) is supplied with this version of
Powerbase. It was created from the ‘Elements’ database and is intended to
work with the sample Ovation document ‘OmergeTest’. Before attempting to
create CSV files of your own you are recommended to read the Powerbase
documentation on such files. The process for mail-merging with Ovation is
described below.

Preparing an Ovation document for mail-merging
———————————————————————
NOTE: This feature does not seem to be supported by Ovation prior to version
1.36 and it is to that version that the following information applies. I
would like to take this opportunity to thank RISC Developments Ltd. for
supplying a copy of Ovation to facilitate this documentation.

Ovation has a very easy method of specifying where the merged data is to go
into the document. Whenever you reach a point where you wish to insert a
Powerbase field type CTRL I. A small dialogue box (‘Merge tag’) will appear
inviting you to enter a number. The number required is the field number in
the CSV record (which is NOT necessarily the field number in the Powerbase
record). If, for instance, you wish to merge the second field from each line
of your CSV file enter 2 and type RETURN. You will see that [Merge2] has
been inserted into the text at the caret. Continue typing, inserting other
fields as required. The fields do not need to be in numerical order (you can
insert field 2 before you insert field 1) and the same field may be inserted
many times. Styles and effects may also be applied to the Merge tags. Load
‘MergeTest’ to see how this looks.

With ‘MergeTest’ loaded open the main Ovation menu, go to the ‘File’ submenu
and choose ‘Print’. Select the ‘Mail merge’ option button and drag
‘OvationCSV’ to the writable icon to the right of the button. The pathname
of the file will appear in the icon. Click on ‘OK’ and the document will be
printed once for each record in the CSV file, merging new data into the
document each time. ‘OvationCSV’ contains 10 records so if you just want to
see the process in action without actually printing 10 sheets of paper set
your printer manager to print to a file instead of to the printer itself.

If you examine ‘OvationCSV’ you will see that each field is enclosed in
quotes. This is only necessary of the fields contain literal commas. Look at
the first record, for example, and note the comma in “(Gr.aktis,aktinos; ray
or beam)“. Without the quotes Ovation would interpret the comma as a field
separator and the merging would be out of step for that record.

Mail-merging with Impression
============================
Powerbase and Impression are able to communicate directly with each other
without the need for a CSV file. This task is performed by a module called
ImpulseII which Computer Concepts have placed in the public domain to
encourage its adoption as a standard means of transferring data between RISC
OS applications. The ImpulseII module is included in the ‘Resources’ folder
inside the Powerbase application directory.

Preparing the Impression document
————————————————-
Since the merged data is not being supplied from a pre-generated CSV file
Impression needs to request specifically each Powerbase field that it
wants to merge into the document. It is probably best to create the document
without worrying about the merged data at first, then insert the necessary
commands afterwards.

Wherever you want data from a Powerbase record to appear in the document
proceed as follows:-

(1) Place the caret at the point where the data is to be inserted.

(2) Click MENU over the frame, go to the ‘Misc’ submenu and choose ‘Merge
command...‘. A dialogue box will appear.

(3) Type the following:-

                :Powerbase GetField NAME

This is on the understanding that your Powerbase record contains a field
whose tag is NAME and that you want the contents of that field inserting
into the Impression document at that point. Note the spaces and the initial
colon. These are essential.

(4) Click on ‘Set’ or type RETURN. You will see “<Merge>” appear in the
    text.

(5) Repeat for all the other Powerbase fields to be inserted in the
    document. All take the form :Powerbase GetField <tag>. All the data in a
    given document must come from the same database. It might be easiest if
    you open the required database and arrange the desktop so that you can
    see both the record window and the Impression document. Clicking MENU
    over a field makes its tag appear in the second menu item.

(6) Save the the document!

When you look at the document there is nothing to distinguish one merge
command from another; they all appear as “<Merge>”. To check on what a
command actually looks like open the ‘Merge command’ dialogue box again
and place the caret at the beginning of the merge command, i.e. immediately
before the initial “<”. The text of the command will then appear in the
writable icon of the dialogue box.

Merging the data
————————
(1) Make sure Impression has been “seen” by the filer. Impression doesn’t
    need to actually be on the icon-bar at this point but it doesn’t matter
    if it is.

(2) Open the Powerbase database.

(3) Drop the Impression document on the record window. If Impression isn’t
    already running Powerbase will run it for you. Assuming that the
    document isn’t loaded already it will be loaded and displayed. Finally
    Powerbase’s ‘Data merge’ dialogue box will appear. (If the document is
    already loaded Impression will print a message informing you of this.
    When you click on ‘OK’ the ‘Data merge’ box appears and you should then
    display the Impression document with ‘New view’.)

(4) The ‘Data merge’ window has a writable icon in which you may enter a
    search formula (see ‘!Tutorial’ and ‘Print’). Clicking on ‘Merge’ or
    typing RETURN then extracts data from the first matching record and
    inserts it in the specified places in the Impression document. If no
    search formula was entered the merged record will be the first.

(5) Buttons are provided for “next”, “previous”, “first” and “last” record.
    These work just like the corresponding keypad buttons and the Impression
    document displays the merged data in each case.

(6) Clicking on ‘Print’ will print the Impression document in its displayed
    state, i.e. with the currently merged data. If you select the ‘Print
    all‘ switch then click on ’Merge‘ a whole series of hard copies will be
    produced, one for each matching record.

(7) Note that when the mouse pointer is moved over the Impression document
    after you have clicked on ‘Merge’ it changes to a large red and blue
    cross which means that you cannot edit the document. Clicking SELECT
    over it has no effect; the caret doesn’t appear. If you click on
    ‘Cancel’ in the dialogue box the merged data is removed from the
    document and normal editing is restored.

Mail-merging with other programs
================================
If you use neither Impression nor Ovation you may still be able to use
mail-merging with your wordprocessor, but you will need to read the manual
carefully to find out how. It will almost certainly involve a CSV or similar
file in conjunction with some method of “tagging” the document (as described
above for Impression and Ovation) to specify where in it the data is to be
merged.

Powerbase as an ‘Impulse’ server
================================
The following is a description of the Impulse “methods” understood by
Powerbase, given in the standard format recommended by Computer Concepts.
Users wishing to write their own Impulse tasks to communicate with Powerbase
will need this information. They will also need details of the SWIs to which
Impulse will respond, and this information is obtainable from Computer
Concepts.

{methods: GetPathname
        Selection <string>
        ParseQuery <string>
        GetField <tag>
        GetRecord
        PutFile
        ExpandCode <string>
        GetExpanded <string>

Descriptions:
GetPathname

Specifies an ‘object’ i.e. a Powerbase database. If Powerbase has the
required database open it replies with the full pathname of the object,
otherwise it returns an error message. Example of use:

  :Powerbase !Elements GetPathname  (returns pathname of !Elements)

R6 points to pathname when calling task is decoding reply.

Selection <string>

Tells Powerbase about a field, or group of fields, in which the caller is
interested. The fields are specified as a list of tags, separated by any
suitable character (e.g. / or ,). The same separator must appear at the very
end of the tag-list.  Powerbase replies with the maximum data-length of the
combined fields in the selection. Example of use:

  :Powerbase Selection NAME/SYM/Z/

R6 points to a string which gives data-length.

ParseQuery <string>

Informs Powerbase of the criteria to be used in selecting records to
transmit to the caller.  The parameter is a standard Powerbase search
formula and Powerbase replies with the title which would normally appear
at the head of one of its printed lists. Example of use:

  :Powerbase ParseQuery TYPE=T

R6 points to returned title.

GetField <tag>

Requests from Powerbase the data in the specified field of the next record
which matches the preceding ParseQuery command.

When Powerbase replies to the GetField command the calling task should
respond with an ImpulseFetchData, specifying the address and length of the
buffer to be used, and then wait for an Impulse_receive event (reason code
&204) before reading the buffer.

GetRecord [<key>]

Sent without a key it requests from Powerbase the next record which matches
the preceding ParseQuery command. If the primary key of a record in the
database is appended then Powerbase will return the record corresponding to
that key. The key must be separated from the GetRecord by a space.

The calling task must follow the procedure described above for GetField.
Powerbase will transmit the fields specified in the Selection command, using
the same separator as was used in that command. Receipt of data may be
followed by another GetRecord command, returning the next matching record
and so on, a zero-length response signifying that there are no more
matching records. If using keys to request specific records you should end
by sending *** as a key to tell Powerbase that the dialogue is finished.
This command and the one below operate only on Subfile 0 of the Powerbase
database.

PutRecord

Informs Powerbase that the caller wishes to write a record to the current
Powerbase database. It should be sent as message type &200. A Selection
command should have been previously sent to tell Powerbase what fields to
expect and what separator is to be used. Powerbase will then reply with a
GetRecord command (reason code &201) which the caller should acknowledge
with message type &202, specifying the maximum length of the data which will
be sent. Wait for event &203 which is a request by Powerbase for the caller
to transmit the data. The caller should then do so with ImpulseTransmitData,
specifying the buffer address and the length of data being sent. This may be
immediately followed by  another PutRecord.

ExpandCode <string>

Requests the expanded form of a code used in a field linked to a validation
table. The parameter string consists of the code itself, then a space,
then the name of the validation table with the column number appended.
Example of use:

  :Powerbase ExpandCode T Group0

GetExpanded <string>

Combines the functions of GetField and ExpandCode, i.e. it requests the
expanded form of the contents of a specified field. The parameter string is
similar to that for ExpandCode, except that the field tag is substituted for
the code.
Example of use:

  :Powerbase GetExpanded GP Group0

}