Arco Word Reporter 2.1 - by CC+CC

by Drew Bourrut

Published 1999-02-01    Printer-friendly version

There are products you like. There are products you review. Often there are products you like to review. But rarely are there products you’d give your eyeteeth to review. This is one. For several years I have been interested in interfacing Clarion apps with other products and with a word processor in particular (you may be aware of my review of RichX some time ago).

Introduction

The name says it all: Arco Word Reporter (AWR). The product allows you to use Microsoft Word as the recipient of a Clarion report. Another way of thinking about this is that, after creating the report, it appears as a document in MS Word. This means that you have all of the formatting capabilities of MS Word for your Clarion reports, and it also means that you can do final editing to a report before final print. The possibility of this excited me greatly.

Then I viewed the documentation - and was scared to death. This is not to say that the product is hard to implement. CC+CC, the makers of Arco Word Reporter, have apparently decided that you may not fully understand what the product is all about, and so launch into an explanation of the product (with diagram) followed by almost four and a half pages of Class Methods and Properties followed by almost two pages of very detailed installation instructions. Whew!

My Approach: Tutorials first

Installing Arco Word Reporter

I began by following the installation instructions. You must follow them meticulously. These instructions require that you copy files to a variety of directories and then register the OCX as well as the templates. This required a few careful minutes. While installing, I had a problem finding one of the files I needed to copy so I emailed arco@cccc.ch and they responded quite promptly with an answer. By the way, their website www.arcosoftware.com has a "frequently asked questions" area, and you’ll note my problem has made its way onto the list.

Tutorials (yes, there are more than one)

If you put the effort into understanding this product I think you will be very happy with it. CC+CC understands this and have created several tutorials to help you understand their product.

First, an aside. My mom is eighty-two. She has never used a computer and, one day when I was at her home, she asked me about e-mail. I tried to explain the idea (yes, this is relevant). She didn’t get it and was clearly more confused. I tried again. No luck. I tried a third time and did no better. Finally, I said that the next time she came over to our house I would show her e-mail, and I did. At the end of the demonstration she said, "That’s it? What’s the big deal?" She still didn’t know what happened behind the scenes but she knew about e-mail. I feel the same way about this product.

As I told you, the documentation intimidated me (as did the tutorials), but after doing them I felt a lot better. I felt I understood how the product worked and what I needed to do to use it in my own applications. There are three tutorial applications: tutor.app you can simply compile and run to see what the product can do; atutor.app is the tutorial app that you will use with the tutorial in the documentation; and btutor.app which is a successfully completed version of atutor (I couldn’t have done without it).

This said, I did step through the tutorial, which required that I write a couple pages of source code. My first reaction was to be annoyed at all the coding. But as I did it I found I was gaining insight into how the product works. Here’s a rule: Do the tutorials!

After completing the tutorial I compiled it and scratched my head looking at the errors. I fixed a series of errors that were mine (periods instead of commas, and some typos) and removed two lines of code that were done correctly but that produced errors. Now the app compiled with no errors but, when run, failed to work correctly. At this point I fired a question off to CC+CC asking about the two lines I had removed that I couldn’t get to compile correctly.

Once that was done, I was about to stop for the day when I happened to note the following sentences: "If something went wrong we also provided the finished tutorial. Checkout bTutor.app!" So I did and found that I had some code in the wrong embed. The documentation really wasn’t clear. Honest, it wasn’t me. Once I made the changes the application worked flawlessly.

Preparing for my own application

You might think that I was now ready to do my own application. Wrong! The way AWR works is to send stuff to Microsoft WordÒ that is then formatted based on an existing RTF file and a DOT (Document Template) file. It seemed like a good idea to take a look at both. The DOT file was very simple. Here it is:

Word)

We’ll look at this in more depth later. But first lets take a look at the RTF file.

Word)

Amazing! This is scary! Well, perhaps not that scary but it illustrates a point. You must understand this stuff also to effectively use the product, and we’ll look at it in more depth.

I decided that I had better understand this stuff before I attempted to use AWR in my own application. So what follows is my understanding of how the products (AWR and Word) work together. Here is an explanation (slightly modified) from the AWR documentation.

Workflow

Essentially, your program invokes the AWR CLASS, which then reads the MS Word template looking for bookmarks. AWR loops through the bookmarks and, for each found bookmark, asks your program to replace them with values from your program’s data files and pass the replacements back to AWR. At this point, it is either ready to process the next document (as in a multi-invoice report) or is finished making MS Word visible and finishing the communication. Note that MS Word uses the RTF file as the basis for what it does with the data from AWR and your application. Here is a sample result.

in Word)

Pretty impressive! As I said, it seemed (and it was) important to understand how this all worked together so I began by examining the AWR documentation’s discussion of the document template and to examine the template file. I checked out the following: Pasadena, @invoicedate@. The documentation points out that:

• "A word template (DOT) defines the basic layout including the field names to be replaced by variable data. When data has to be formatted into tables with multiple rows (invoice details, order list…) a style file in RTF format is used to define the rows of the table.
• "The fields in the template are identified by a @ at the beginning and the end.
• "Sample fields: @invoicenumber@ @grand total@ @order list@"
• The documentation further explains:
• "For tables like an order list a style file is used. It defines the appearance and the fields to be replaced with data for a specific type of row (header level 1, header level 2, order detail, tax detail, total level 1, total level 2, grand total...). 99 different styles can be defined in a style file.

Word showings Gridlines")

As you can see, any formatting Word allows can be used!

Rules

• Templates

1. Create a document, place the fields, save as word template (*.DOT). The same fields can be used in different places, even in the header and the footer. The size of a template should not exceed 2MB, so be careful with graphics.

• Fields in a template

1. They need a @ on both sides: @order date@
2. Their names must not exceed 30 characters (excl. @)
   - they can be replaced with single data up to 1KB, or
   - they can be replaced with tables/lists using also styles
3. The entire field must be formatted in the same manner (incl. @) (same font, size, color...)

• Style Files

1. Create a document with 1 to 99 style definitions
2. Save as Rich Text Format (*.RTF) document

 

• Style Definition

1. A style definition consists of two lines
2. The first line begins with @STILii where ii is a number between 01 and 99 followed by the purpose of the style
3. The second line is one single table row with at least one cell
4. Application-specific fields can be placed in the cells. There is no restriction to the fields because you have to implement the replacing of the fields in a style row with data. The interface gives you an entire row and rewrites the data-completed row back.

So now, how does this relate to what’s going on in the application? Well here goes.

As with most Clarion tools, the first step is to add a global extension to your app. Then you must also add a bunch of global variables (16 by my count). Then the main procedure gets an embed to read from an ini file. Beyond this, everything sort of depends on what you’re planning to do. In the case of the atutor.app, it shows a browse with a list of orders or invoices, and you can print (send to MS Word) any invoice. On the browse is standard logic to make sure that the current record is in memory and ready. The browse has a print button that calls a PrintOrder procedure where all the critical logic is contained. This is what we’ll look at here because its what helped me to understand what was going on.

The PrintOrder Procedure

This procedure is a window with a lot of logic going on. A procedure extension template is added and filled out according to instructions in the manual. Then source code (remember all the source code I had to type?) is inserted into various embeds. There’s code to read the order; read in a record from another file (the print layout record) that defines what template (DOT) and what Style (RTF) files are to be used. Then finally there is one more procedure (containing the most source code) and here it is (mildly edited for formatting):

MyWord.ReplaceBM    Function(String InStr)
  Code
  !// This method is called from MyWord.MakeDoc(). The Inputstring (Instr) contains
  !// a bookmark that AWR has found. You decide what to do with that.
  CASE Upper(InStr)         !Use Upper so your user can use mixed case
    OF 'INVOICEDATE'                      !Single field
       MyWord.WriteField(Format(ORD:Oda,@d6))
    OF 'INVOICEADDRESS'                   !Another single field
       MyWord.WriteField(Ord:Adr)
    OF 'ORDERTYPE'                        !Another single field
       MyWord.WriteField(Ord:oty)
    OF 'INVOICENUMBER'                    !Another single field
       MyWord.WriteField(Ord:Nr)
    OF 'SUBJECT'                          !Another single field
       MyWord.WriteField(ORD:Ote)
    OF 'ARTICLELIST'
       !First print a Header - Stylenumber 13
       If MyWord.GetStyle(13)             !found the style
          !Define the Bookmarks and values to replace
          !The first cell is the one you definded in the style file
          !the 2nd one is the value that replace the bookmark (cell 1) in the style file
          !Note that you can define everything CW allows in the 2nd cell
          !ie: format, clip etc. (see below..)
          MyWord.WriteCell('@pos','Position')
          MyWord.WriteCell('@txt','Items')
          MyWord.WriteCell('@qty','Quantity')
          MyWord.WriteCell('@prs','Price')
          MyWord.WriteCell('@tot','Total')
          MyWord.WriteStyle()                    !Send that to word
       End
      !Now we need an empty line for spacing
      IF myWord.GetStyle(01) then MyWord.WriteStyle() end
      !Go through the items database and print the single records
      Ite:Ord = Ord:Nr
      Clear(Ite:Nr,-1)
      Set(Ite:Key_Ord_Nr,Ite:Key_Ord_Nr)
      Loop
        next(Items)
        If ErrorCode() or Ite:Ord not = Ord:Nr then Break end
        !Depending on the status of the item we choose a style
        Case Clip(Ite:Sta)
          of 'on stock'
             IF not myWord.GetStyle(11) then cycle end
          of 'delayed'
             IF not myWord.GetStyle(15) then cycle end
        End
        Case Clip(Ite:Sta)
          of 'on stock'
             myWord.WriteCell('@pos',Ite:Nr)
          of 'delayed'
             myWord.WriteCell('@pos',ITE:Nr &' del.')
        End
        myWord.WriteCell('@txt',Clip(ITE:Ite))
        myWord.WriteCell('@qty',Format(ITE:Qua,@n-_10.2))
        myWord.WriteCell('@prs',Format(ITE:Pri,@n-_10.2))
        myWord.WriteCell('@tot',Format(ITE:Tot,@n-_10.2))
        myWord.WriteStyle()                 !Send that to Word
        Loc_Sub += ITE:Tot                  !Count for subtotal
      END
      !Now we need another empty line for spacing
      IF myWord.GetStyle(01) then MyWord.WriteStyle() end
      !Print subtotal - Stylenumber 32
      IF myWord.GetStyle(32)
         myWord.WriteCell('@txt','Subtotal')
         myWord.WriteCell('@tot',Format(Loc_Sub,@n-_10.2))
         myWord.WriteStyle() !Send that to Word
      End
      !Print tax - Stylenumber 14
      Loc_Tax = Loc_Sub * 9.5 / 100
      IF myWord.GetStyle(14)
         myWord.WriteCell('@txt','Tax 9.5%')
         myWord.WriteCell('@tot',Format(Loc_Tax,@n-_10.2))
         myWord.WriteStyle() !Send that to Word
      End
      !Now we need another empty line for spacing
      IF myWord.GetStyle(01) then MyWord.WriteStyle() end
      !Print Grandtotal - Stylenumber 33
      Loc_Tot = Loc_Sub + Loc_Tax
      IF myWord.GetStyle(33)
         myWord.WriteCell('@txt','Total')
         myWord.WriteCell('@tot',Format(Loc_Tot,@n-_10.2))
         myWord.WriteStyle()                  !Send that to Word
      End
  Else
      Return(False)                           !No Bookmark to replace
  End
  Return(True)                                !Bookmark replaced

You’ll notice at the beginning of the code where items from the DOT are read in and replaced. Then you’ll note the style information is read in and header information is replaced, as well as the individual detail lines with final totals summing up.

I’ve edited this code very slightly but only to change word wrapping so that you’ll get the idea of what’s involved.

My own application

Finally, I was ready to produce my own application. It would not be fair to you for me to now spend pages detailing my own application. Suffice it to say that I successfully added AWR to my app and it works!

Support

During my initial attempt at installing the product I ran into a minor problem as mentioned earlier. An e-mailed message brought a quick response (within 24hours) that was right on the money. When I had my problem with the demo app I sent of a message, but before the CC+CC staff could respond I had figured out what the problem was by examining the additional tutorial application. However, I chose to wait for their response to see how well they diagnosed the problem. The problem was that I has inserted code into the wrong embed. They responded again within 24 hours asking some questions to which I responded. Their questions made it clear to me that they knew their product well and their final response not only explained what was wrong but also suggested an alternative approach. Nice job.

Documentation

For such a product I initially thought the documentation (23-page DOC file) was a little thin. However, as I used it I found it to be quite good. The approach of initially telling me more than I thought I wanted to know turned out to be the proper approach. The document is highly readable, which may surprise some considering the writer’s native language, I suppose, is Schweitzer-Deutsch.

Room for improvement

Let me be clear. The product works! That said, I believe I given you the feeling that it is a fairly complicated product to use right from the moment of installation. I would like to see the installation process made simpler.

Next, since there is a fairly long list of global variables to be added, it would be nice if adding the global extension template would also cause the variables to be added. Finally, the tutorial could be beefed up a little. Particularly the explanation of which embed to use. It would have eliminated a support question. Overall, a very nice product if a little bit intimidating.

The Ratings

Sometimes it’s hard to do these ratings. This is one of those times. On the one hand, the product works, and works well. On the other, it requires a fair amount of coding and the setting up of the DOT and RTF files (The RTF file setup is not insignificant). So here goes.

Category	Product Score
Ability to do the task	Very Good
Ease of use	Good
Ease of Installation	Very Good
Documentation	Very Good
Technical Support	Excellent
Modifies Shipping Templates	No
Black-Box DLLs/LIBs	Yes

The ARCO Word Reporter lists for US $295, and is available directly from CC+CC as well as from Topspeed (1-800-354-5444). AWR is compatible with C4 and C5, using either legacy (Clarion) or ABC template chains.

More information, frequently asked questions and a demo can be found at: http://www.arcosoftware.com/devtools/devtools.html (Note: This is the only English language section of their web site.)

Vendor Comments from ARCO/CC+CC

First of all we are very happy about the test results and would like to say thanks to Drew for his great work and the opportunity to be tested in ClarionOnline.

We know it’s not that easy to work with our Tool; you have to spend a couple of hours to really understand how everything goes together but the results are sure worth the work.

Vendor comments from CC+CC

A couple of things we like to add/clarify Black-Box DLLs/LIBs - It’s true that part of AWR is an OCX written in VB. We developed it in VB because we were not able to do it in Clarion. This will change with the new OLE methods from TopSpeed that are currently in Alpha Status. This means you’ll get the whole sourceà will also affect point 2 Installation - Due to the need of above OCX you have to register it to Windows which is not always that easy (thanks Bill). Once the new OLE methods are out you won’t have to do that anymore. All you (and your users) need is a working Word – that’s all! Finally you only need to install the template (2 Files) and the classes (2 Files) and NOTHING else!! Long list of global variables - There are many ways how to use the reporter. For example in tutor.app you find no global variable. In btutor.app we showed you a possibility how you can store your users preferences. It’s a must that you are familiar with handcoding and we do not support you with that in form of a template. At first sight this looks like a con but on the other side this is a pro. You have total control over the printout. Ever tried to print 2 child files with Clarion’s report generator on the same detail band <g>? As Drew said DO THE TUTORIALS – once you are over the learning curve you’ll love it! If you have problems with the tutorial we are happy to support you by email – usually within 24 hours! One thing we really like to add - and in our opinion very important - is the possibility to create documents in HTML format. We always improve the usability and flexibility of AWR and its documentation so watch out and visit our homepage from time to time (we also announce that in TopSpeeds 3rd party newsgroup). Ok, thanks for reading and now back to reporting! Reto Camenzind & Hanspeter Stutz CC+CC - Switzerland

Printer-friendly version

Copyright © 1999-2008 by CoveComm Inc. All Rights Reserved. Reproduction in any form without the express written consent of CoveComm Inc., except as described in the subscription agreement, is prohibited.

Clarion Magazine ISSN 1718-9942