There is a completed example, in which all of the below steps have been followed, in your clarionx\3rdparty\examples\RightReports\abc folder.

Step  1: Install the latest versions of Draw, RightReports and Clarion FreeImage.

• Note that you need Draw version 2.53 or later for RightReports to work.
• Note that besides running the FreeImage install file,  you will also need to download the FreeImage DLL and put this in your clarionx\3rdparty\bin directory.
• Make sure that you pick the option to register the template for each of the three installs, if they are not already registered.
• Note: There are two templates to be registered by the installer. The first is RightReports.tpl, and the second is editin.tpl. In some cases registration of the latter fails. If it does, you will get an "Unknown Template Type (EditInPlace) " type error when trying to open one of the example apps, or an app with the RightReportsUpdate procedure in it. To fix this, go to "Template Registry" under the Setup Menu and register editin.tpl in clarionx\3rdparty\template.

Note: You can get by without Clarion FreeImage, but it does very much limit the type of image files you will be able to use in your reports. In fact, you will only be able to use bitmaps.

Step  2: Import the RightReports Tables into your dictionary.

• Open your dictionary in the Clarion IDE. 
• Choose File|Import Text.
• Go to your Clarionx\3rdparty\Libsrc folder.
• Choose the RightReportsTables.txd file and Open it.
• Save and close your dictionary.
• If you are using an SQL backend, dont forget to fill in the Owner for each imported table.
• If you are using FM3 or FM2, dont forget to add the Version option (set to 1) under the Table Options for each imported table.

Step 3: Import the RightReports Procedures into your app.

• Open your application in the Clarion IDE.
• Go to File|Import Text ...
• Import the RightReportsFunctionsABC.txa or RightReportsFunctionsLegacy.txa file in your clarionx\3rdparty\libsrc folder
• See the section on Imported RightReports Procedures for more info on the imported procedures.

Step 3a: Import the RightReports Import and Export Procedures into your app.

• Note You need xFiles 1.61 or later for these procedures to work.
• Go to File|Import Text ...
• Import the RRImportExport.txa file in your clarionx\3rdparty\libsrc folder.
• See the section on Importing and Exporting Reports for more info on the imported procedures.

Step  4: Add the FreeImage, Draw and RightReports global extensions to your app.

• Open your application in the Clarion IDE.
• Click on the Global button.
• In the Global Properties window, click on the Extensions button.
• Click on the Insert button and select the Activate_ClarionFreeImage extension template.
• Click on the Insert button and select the GloDraw extension template.
• On the General Tab of the Draw Global Template, tick the “Activate DrawImage” and “Activate DrawPaint” options.
• Click on the Insert button and select the Activate_RightReports (Activate RightReports Functions) extension template.
• Click OK and OK again.

Step  4a: Multi-DLL Applications

If you have a multi-DLL application and have added Draw to your Data DLL, the way to add the global extentions is as follows:

• Add the Draw Global Extention to the Data DLL, and on the General Tab, tick the “Activate DrawImage” and “Activate DrawPaint” options.
• Add the Global Clarion FreeImage extention to the Data DLL, too
• Add the Draw Global Extention to your reporting DLL, and on the General Tab, tick the “Activate DrawImage”,  “Activate DrawPaint” and "Use Draw that is exported in another DLL" options.
• Add the Global Clarion FreeImage extention to your reporting DLL
• Add the Global RightReports extention to your reporting DLL

Step 5: Tick the Generate All File Declarations option for your app.

You can find this by clicking on the Global button and going to the File Control tab – it’s the first checkbox. If you don’t do this, RightReports will only pick up tables you’ve specified in the table tree structures of the procedures in your application, and you will hence be able to use only these tables in your reports at runtime. Ticking this option ensures that RightReports makes all the tables in your dictionary available to the end user.

Step 6: Call the RightReportsBrowse procedure from somewhere in your app.

This is a browse for all the reports that have been created in your program. Make sure you call the RightReportsBrowse procedure with parameter 0 for now, i.e. call RightReportsBrowse(0). If your application has a Frame, adding a Browse Reports option to one of the menus might be an idea.

Step 7: Ok … Go!

Compile and run your app.

You will notice that one of the steps explained above while adding RightReports to your application involved importing a number of procedures. Below we give a short description for each of these procedures.

• RightReportsBrowse: This is the browse containing all the reports created in your application.
• RightReportsUpdate: This is the Report Editor. Its the window that pops up when you choose to edit a report in the browse above, and is actually a form that updates the report tables.
• RightReportsOverrideParentFile: This is a window that will pop up when you choose the edit the parent file of a Secondary Loop or Lookup.
• RightReportsPremier: This is the built-in RightReports report previewer.
• RightReportsPrint: RightReportsPrint is the procedure responsible for printing the report created by the report editor. There is a special section on RightReportsPrint giving more information.
• RightReportsSendEmail: One of the options when printing a report is to send it off via email. Put your code for emailing the report in here. NetTalk is a useful and quick way to add this emailing functionality.
• RightReportsViewTextFile: This is the built-in RightReports report previewer for text reports.
• RightReportsImportTXR: This imports the specified TXR file into RightReports. Users can then edit and print the imported reports as usual. See also the section on Importing and Exporting Reports.
• RightReportsExport: This exports the specified report to an xml file. Users can the use the below procedure to import the report. This is useful for making reports mobile - for example, you could design the report on your end and then just email the exported xml file to a client, who can then import the report again. See also the section on Importing and Exporting Reports.
• RightReportsImport: This imports a report from a specified xml file. See RightReportsImport above for more details. See also the section on Importing and Exporting Reports.

The Global Extension

The General Tab

• Disable All RightReports Features: Use this for debugging.
• Enable Web Server in PrintReport: If you have added NetTalk 4 to your application and want to be able to use RightReports with your web server, tick this option. Not fully supported yet.
• Enable Printing to PDF: If you want RightReports to be able to output to a PDF file, tick this option. You need the abprpdf class files for this - if you have Clarion 6 Professional Edition, this is included.
• Use HyperActive to preview PDF Files: If you have HyperActive Installed and added to your application, you can tick this and PDF files will be previewed using HyperActive.
• Previewer: RightReports: Choose this option if you want the built-in RightReports Previewer to preview printed reports.
• Previewer: ABC: Choose this option if you want the built-in ABC Previewer to preview printed reports.
• Previewer: IceTips, RPM or CPCS: You can also choose to use other 3rdparty report previewers. Depending on your choice, a new Tab may appear with options for that previewer, as is discussed below. See the section on The Report Previewer for more details on how to use these options.

The Previewer Tab

Depending on your choice of Report Previewer, a tab may appear with options for that Previewer. These are basically the options for that previewer as they would appear if you had installed and used that 3rdparty tool directly. Consult the documentation that came with that tool for more information on the available options. See also The Report Previewer for more details on how to install and use these 3rdparty report previewers.

The Files Tab

On this tab you can override the fields you included or excluded from the Files List in your dictionary. This is useful for if you have more than one Report Editor in your application and you want to switch some of your tables on and off at DLL level rather than for the entire application.

• Suppress Files: Select the files that you don't want to appear in the report editor for this DLL.
• Include Files: Select files here that were excluded in the dictionary but you still want them to appear in the report editor for this DLL, Tree Defn File, Calcs File, Totals File, Secondary File

The Advanced Tab

• Class is External: Tick this if you have a Multi-DLL application, and the Global Extension was added to a different DLL (i.e. if the RightReports class was compiled into a different DLL).
• Don't Link: Indicates that the class should not be linked in locally, it is external (in a DLL, not local).
• RightReports Based On: A super-advanced option allowing you to specify which class RightReports should inherit from.
• Tables per FQ module: For each table, a number of procedures are generated by RightReports. Originally, each table had its own module created by RightReports into which these procedures were generated. These modules are named something like repFQ1.clw, repFQ2.clw, etc. where "rep" is the first three letters of your application name. Since lots of tables hence means lots of FQ modules, you can specify here how many tables' procedures to generate into one FQ module to reduce this number. The default is 5.

The RightReports Files Tabs

You will notice that there are a number of other tabs on the Global Extension, such as Report, Band File, Controls File and Fields File. For the most, you will not need the tabs. If you, however, decide to rename some of the Imported RightReports Files or their fields, then you would possibly have to come to this tab to make sure all the table names, and their related field names, are still filled in correctly on this tab.

The Local Extension

The General Tab

• Disable Here: Use this to disable RightReports in this procedure. For debugging purposes, mainly.
• Show Ruler: You could have a ruler along the bottom of the graphic display area, if you wanted. Not fully implemented yet.
• Background Color: Set this to the colour you would like the background of the Graphic Band Editor to be.
• Gap Between Bands: Set this to the number of pixels you want to separate bands with in the Graphic Band Editor.
• Call Procedure to Update Control Properties: Usually you edit the properties of the selected control using the Property Tab. However, you could also add functionality to allow the user to edit these in a window via choosing an option from the right-click menu.
• Update Procedure: If the above option is ticked, enter the name of the update procedure for the control properties here.

The Hot Keys Tab

On this tab you can specify hot keys for editing and moving controls in the Graphic Band Editor. The prompts are rather self-explanatory.

The Advanced Tab

• Object Name: The name of the RightReports object in this procedure.
• Based on Class: A super-advanced option allowing you to specify which class RightReports should inherit from. By default it is whatever class was specified on the Global Advanced Tab. Once again its best if you leave this sucker alone.

The Browse Window

The RightReportsBrowse procedure lets you browse the current reports in your program.

It shows the date and time at which the report was last modified as well as the description. If you click the Add or Change button, you can edit this graphic report at runtime. The update procedure is called RightReportsUpdate.

The Update Form

The RightReportsUpdate procedure allows you to create and edit graphic reports with ease. There are three sections to this window:

• The Report Structure List on the left
• The Graphic Band Editor on the right
• The bottom left Property Sheet

The Report Structure List

This list allows you to specify a primary file, and add graphic report details, lookups, secondary file loops, calculations, headers and footers to your report. A short description for each of these is given below.

Note that you can move each item up or down depending on where on the report it should happen. You can also move each item left or right. If an item A is left of any item B above it, it means that that item B is a parent of item A.

• Primary File: This specifies the primary file for the report.
• Lookup: If the current file has a many-to-one relation with another file, this can be used to look up the related record in that related file (by current file we mean the file of the closest parent that is either a primary file or secondary loop).
• Secondary Loop: If the current file has a one-to-many relation with another file, this can be used to loop through the related records in the related file.
• Calculation: Use this to perform a calculation and set a variable.
• Header: This is the header band for the report. There can be only one.
• Footer: This is the footer band for the report. Ditto re. the cheesy quote above.

The Graphic Band Editor

Any detail, header or footer created using the Report Structure List above appears in this editor. Check out the cool editing functionality available to you:

• Use the provided buttons to add boxes, strings, images and lines to any of the bands.
• Resize the bands and controls on the bands.
• Right-click and observe the neat popup menu allowing you to do things like align controls and copy-paste. Holding down the Control Key allows you to select multiple controls at once.

A note on Strings: Putting angular brackets around a word indicates to the report printing engine that this is possibly a local or global variable (see the Property Editor below), or a field in one of your report tables. See the Printing Variable and Field Values section for more details.

The Property Editor

This feature allows you to edit various properties belonging to the currently selected item in the Report Structure List. If a control is selected in the Graphic Band Editor, it allows you to edit the properties for that control. The property editor has several tabs:

• The Properties Tab: On this tab you can edit various properties for the selected item or control, including the text value, colors and position.
• The Totalling Tab (Only for Secondary Loops): You can create totals that are automatically calculated through the loop for the specified field.
  Note: The field has to be present somewhere on a band that has the loop as parent for the total to be calculated correctly.
• The Fields Tab: This just displays all the tables that are used in this report, with their fields and descriptions.
• The Functions Tab: This displays the functions available to the user. You have to create these yourself in your app, bind them in the BindRep procedure and add them to the AddCustomFunctions procedure (see the next step for more on this).
• The Global Tab: This is a list of global variables available to the user for use in the report. The user can edit, add and remove these at will. They are global in the sense that they are available to all reports in this program (see the next step for more on this).

• The Local Tab: Similar to the Global Tab, except that these variables are only available to the current report in the program.
• The Notes Tab: Write any general notes regarding the report here. There's lots of space, so go wild.

The Print Window

When you have finished editing the report, you can press OK to save it and then click Print on the Browse Reports window. This brings up the Report Options window (the procedure is called RightReportsPrint):

Here you can select where you want to print the file to, choose your printer, etc. Any local or global report variables which were declared of type “User” will appear on this window, allowing the user to specify their values.

You will also notice a Primary Sort dropdown appearing in some cases. This happens when for the Primary File of that report, the user specified “User Selects” for the sort order. If the keys for the file have non-empty descriptions, the descriptions appear in this dropdown. Otherwise the key name appears.

Clicking start sends the printing on its way. See the section on The Report Output for more on the output options.

The Properties Tab on the Property Editor allows you to edit any of the properties relating to the currently selected item in the Report Structure List in edit-in-place type fashion. If a control on a band is selected, its properties will appear in the Property Editor for editing. Below we list the properties for each differrent type of item along with descriptions for each.

A Note on Parent Files

Recall we mentioned that if an item A is left of any item B above it in the Report Structure List, it means that that item B is a parent of item A.The idea of a parent file works more or less the same. The parent file of an item is assumed to be the main file of the closest Secondary Loop or Primary File item above it. It is also possible to override the parent file of a given Secondary Loop or Lookup by changing the Parent File entry on the Properties Tab.

Primary Files

This item contains properties relating to the Primary File of the report, as well as other general

• Description: A description for the report. This description is what appears in the Browse Window.
• Primary File: The name of the primary file through which this report will loop.
• Order By: Choose a key for the primary file by which it should ordered. If you have filled in a description for the key in the dictionary, this description will appear in the dropdown. Otherwise, the name of the key appears.
• Archive: To be updated.
• Order Fields: The fields in the key chosen in "Order By" above. To be updated.  
• Filter: Enter a filter here for the primary file, if desired.
• Format: Choose the format of the report. Opotions are Text, PDF, HTML, Excel, and XML. Some of these are To be updated.
• Graphic: Choose between Graphic and Text reports. This defaults to Graphic.
• Chain To: If you want another report to start printing immediately after this one has been printed, put the report number here.
• Report Number: The report number of this report. This field is not editable.
• Send To: Choose where you would like the report to printed to by default. Choose between Printer, Email, File and Screen.
• Destination: Choose the printer you would like this report to be sent to by default.
• Landscape: Choose whether you want the report to be printed in landscape form by default.
• Report Type: The user can use this at his or her descretion. Useful for grouping differrent types of reports together.

Secondary Loops

• Parent File: If you would like this to have a differrent parent file than the default, choose it here. See the section on Secondary Loops and the Note on Parent Files to see what a parent file is.
• File Name: The name of the Secondary File to loop through. Only files related to this item's parent file in a many to one relationship will appear in this dropdown.
• Cache: To be updated.
• Filter: A filter for this secondary file.
• Range _ From: There may appear a number of these prompts, depending on the key relating this secondary file to its parent files. If there are fields other than fields linking this secondary file to its parent file in the relating key, there will appear such a prompt for each of these fields. Fill in the range from value for this field, if desired.
• Range _ To: There may appear a number of these prompts, depending on the key relating this secondary file to its parent files. If there are fields other than fields linking this secondary file to its parent file in the relating key, there will appear such a prompt for each of these fields. Fill in the range to value for this field, if desired.

Lookups

• Parent File: If you would like this to have a differrent parent file than the default, choose it here. See the section on Lookups and the Note on Parent Files to see what a parent file is.
• File Name: The name of the file to do the lookup on. Only files related to this item's parent file in a one to many relationship will appear in this dropdown.
• Cache: To be updated.
• Linking Fields: This only appears if the Parent File is set to None. This allows you to do a lookup based on a custom relationship between files. What is required here is an expression that links up to three fields in the Lookup file to corresponding fields in the parent file.In other words, supposing the parent file is Invoice and the file to do the lookup on is Customers, it needs to have the following format:

CUS:CField1 = INV:IField1

or

CUS:CField1 = INV:IField1 and CUS:CField2 = INV:IField2

or

CUS:CField1 = INV:IField1 and CUS:CField2 = INV:IField2 and CUS:CField3 = INV:IField3

You also need to make sure that there is a key in the Lookup file that contains each of the lookup fields used in the expression. Otherwise, the lookup will not work.

Calculations

• Calc Name: The name of the calculation. You may call it whatever you like.
• If: A condition for the calculation. Set to 1 if no condition is required. If you are using any variables or table fields in this condition, they should be enclosed by angular brackets.
• Set: The name of the variable to receive the result of the calculation. This variable will have to be declared either on the Global Tab or the Local Tab. You may write the variable names as in, although putting angular brackets around it wont hurt.
• To: The calculation/expression you would like the variable above to be set to. Once again you may use table fields or variables, but remember to put angular brackets around them.
• Else Set: The name of a variable to set if the condition fails. This variable will have to be declared either on the Global Tab or the Local Tab. You may write the variable names as in, although putting angular brackets around it wont hurt.
• To: The value to set the Else Set variable above to. It can be an expression. Once again you may use table fields or variables, but remember to put angular brackets around them.

Details, Headers, Footers and Forms

• Detail/Header/Footer Name: A descriptive name for this band.
• Suppress If Block Empty: This is only valid for bands that appear between a Block Start and Block End statement. What this means is that this band should be printed only if other bands within the block that don't have this option ticked have been printed. A Suppressed detail is indicated in the Report Structure List by putting a star next to it. See the section on Blocks in a Report for more info.
• Block Start: This band is the start of a block. See the Suppress If Block Empty option above for more info. A Block Start is indicated in the Report Structure List by putting a closing angular bracket next to it. See the section on Blocks in a Report for more info.
• Block End: This band is the end of a block. See the Suppress If Block Empty option above for more info. A Block End is indicated in the Report Structure List by putting an opening angular bracket next to it. See the section on Blocks in a Report for more info.
• Hide: Don't ever print this band. But do execute calculations and evaluations relating to this band.
• Width: The width of this band on the report, in pixels.
• Height: The height of this band on the report, in pixels.
• Color: The background color of this band.
• Condition: A condition under which this band should be printed. May be an expression. You may use table fields or variables, but remember to put angular brackets around them. Can be left blank.

Controls

• Text: (String Controls Only) The text of the string control.
• X Pos: The vertical position of the control on the band, in pixels.
• Y Pos: The horizontal position of the control on the band, in pixels.
• Width: The width of the control on the band, in pixels.
• Height: The height of the control on the band, in pixels.
• Fit Width: If this is set, RightReports will adjust the size of the control to its contents when the report is printed, and the specified Width will be ignored. In particular, you can set this to ensure that a string control gets adjusted to the length of its contents when the report gets printed.
• Fit Height: If this is set, RightReports will adjust the size of the control to its contents when the report is printed, and the specified Height will be ignored.
• Transparent: Whether the control should be transparent.
• Background Color: The background color of the control. When editing this a color chooser pops up.
• Foreground Color: The foreground color of the control. Only really useful for boxes and lines. When editing this a color chooser pops up.
• Font Typeface: (String Controls Only) The font name for the string control. When editing this a font chooser pops up.
• Font Style: (String Controls Only) The font style for the string control. When editing this a font chooser pops up.
• Font Charset: (String Controls Only) The font name for the string control. When editing this a font chooser pops up.
• Font Size: (String Controls Only) The font size for the string control. When editing this a font chooser pops up.
• Font Color: (String Controls Only) The color for the string control. When editing this a font chooser pops up.
• Stretched: (Image Controls Only) Whether the image should be stretched.
• Centred: (Image Controls Only) Whether the image should be centred.
• Tile: (Image Controls Only) Whether the image should be tiled.
• File: (Image Controls Only) The file name for the image to display here. Note that the image file has to be in the application directory. For now.
• Line Width: (Line and Box Controls Only) The line width to use when drawing the line or box. In pixels.
• Picture: (String Controls Only) A picture to use for displaying the string.
• Justify: (String Controls Only) Choose whether you want the string to be left, right or center justified within in the control.

Blocks in a Report

A classical example of a Block in a report would be the following:

Suppose you had a secondary loop through Purchased Items for a report on Invoices. For each invoice, you want to print a header, the Purchased Items relating to that Invoice, and then the invoice footer. Naturally, if there are no Purchased Items relating to an Invoice, because they for example have been filtered out, you wouldn't want that entire invoice to print. To achieve this, you would make the invoice header the Block Start and Suppress it, and the invoice footer the Block End and Suppress that too. The actual band with the Purchased Item info on it, however, should be left alone.

The effect that this will have is the following: If there is at least one record in the secondary loop that does not get filtered out and its associating detail prints, all the details within the block will print. However, if there are no valid records and hence no details for Purchased Items print, none of the other details (i.e. the invoice header and footer) will print either.

In your Report Structure List, this scenario would look something like the following:

The stars represents bands with "Suppress if Block Empty" switched on, the closing angular bracket indicates a block start, and the opening angular bracket indicates a block end.

Functions and Variables in the Report

As was mentioned above in the section on the Property Editor, you can add variables to your report using the Global and Local tabs. Placing the name of this variable in angular brackets in a string on the report then causes the value of the variable to print out when the report is printed.

Note that there are three types of variables:

• User: When the report is printed, the user will be prompted on the PrintReport screen for the values of these variables before printing starts. The value for the prompt should be entered in the Else Value field in the list. You can specify the initial value for this variable in the Value field.
• Computed: These variables are computed either by Totalling (see Secondary Loops), Calculations, or they contain the values specified in the Value field in the list. The value in the Value field can be an expression, and can contain calls to functions available on the Functions Tab.
• Conditional: Here you can specify a Condition, Value and Else Value.

If you want functions to be available to the user at runtime, you need to take the following steps:

• Create the function in your application.
• Go to the Global Embeds and look for the RightReportsBind embed point.

• Embed a line of code here that binds this procedure to the name you want the end users to call it by. For example, if  you had a procedure returning the full name of a person given his employee code called GetFullName, you should enter the following line of code:

Bind(‘GetFullName’, GetFullName)

• Add the details for this procedure to the RightReportsAddCustomFunctions procedure. These are the details that will appear on the Functions Tab in the Property Editor. For the above example we would add something along the lines of:

RRFUNC:Name    = 'GetFullName'
RRFUNC:Parms   = '(EmployeeNum)'
RRFUNC:Details = 'Returns the full name of the employee in the form “Surname, Name”, where EmployeeNum is his or her five digit employee number.'
RRFUNC:SeeAlso = 'GetFirstName, GetSurName'
Add(RRFuncQ)

• Remember to Unbind the procedure name in the RightReportsUnbind embed point:

UnBind(‘GetFullName’)

There are already a number of built-in functions that ship with RightReports. Since they are already loaded they’re descriptions can be viewed as usual on the Functions Tab.

Tip: Say you have created your own clip function, called MyClip, and want this function to be called whenever the user calls “clip”. You will notice that Clip has already been bound by RightReports (to the usual Clarion Clip function). You need to make sure you unbind clip before binding it. So your code in the RightReportsBind embed point would be

UnBind(‘clip’)
Bind(‘clip’, MyClip)

Another Tip: Your custom function needs to take only string parameters, and it can only return strings, too. This is a limitation brought about by the Clarion Bind() procedure.

Printing Variable and Field Values

Putting angular brackets around a word indicates to the report printing engine that this is possibly a local or global variable (see the Property Editor), or a field in one of your report tables. When printing the report, RightReports will replace that part of the string with the current value of the variable, or with the value in the field of the current record in the table.

You can find all the local and global variables available to this report on the Local and Global tabs of the Property Editor. All the fields of the tables used in your report can be seen on the Fields Tab of the Property Editor. If your report is a Graphic report, you can drag and drop these fields onto any report band in the Graphic Band Editor above the field list.

Built-In Keywords

There are some built-in keywords such that if they are encountered in a string in angle brackets, RightReports will perform a certain action. The are essentially variables and are treated in exactly the same way. The following are examples:

• <formfeed>: When RightReports runs into this, it immediately starts a new page. For text reports it starts a new page immediately and prints the remainder of the band its on on the next page. For graphic reports, it finishes printing the current band before starting a new page.
• <page>: This will be replaced by the current page number.
• <linenumber>: Only for text reports. This will be replaced by the current line number on the page.

Renaming Table Fields

Suppose one of your table fields has a name that obscures its meaning, such as INV:rn, which stands for the invoice number. It is possible for users to see and use an alternative name in the report editor, which may, for example, be more descriptive and hence easier to work with, such as INV:InvoiceNumber. To do this, take the following steps:

• Go to the table field in your Dictionary
• Go to the User Options of that field
• Enter a new option called RRName and set it to whatever you would like the field to appear and be used as in the Graphic Report Editor

Excluding Tables and Fields from the Files List

There will quite possibly be some tables in your dictionary that you want to hide from the users on the Fields Tab. The way to do this is as follows:

• Go to the table in your dictionary
• Right-click and choose Properties
• Go to the Options Tab
• Insert a property called NoReports and set its value to 1
• Recompile your app

Once you have suppressed a table in your dictionary in this way, you can unsuppressed it by going to the Files Tab on the Global Extension. You will see that it is also possible to suppress files that have not been suppressed in the dictionary here.

In order to suppress specific fields of a given table in your dictionary, the process is the same as the above. You can just follow the five steps mentioned above to add the NoReports user option to the table field in your dictionary.

Preventing Users from Editing a Report

It is possible to prevent users from editing a report by setting the EditAccess property in the RRDefinition file to a value greater than 0. If this is the case for a report, the Update window will open in view-only mode.  The way the value of RRDFN:EditAccess is determined is left up to the programmer, and it is, for obvious reasons, not included in the Properties List for the report on the editor.

Preventing Access to Table Records

It is also possible to prevent a user from accessing certain records in the report tables when printing the report. In fact, it is possible to filter out any records of any table that the report loops through. To do this, you need to take the following steps:

• Go to the Global Embeds
• Look for: RightReportsNextSavFile - Inside Loop
• Expand this tree and look for the file you want to filter
• Insert some filtering code. It may look something like this: if fil:fieldname < 0 then cycle.

The code you are embedding into looks like this:

loop
   next(RRsavFile)
   if errorcode()
     ReturnValue = errorcode()
     break
   end 
   if RRsavFile &= File1

      !Your embed point is here
      if fil:FieldName < 0 then cycle.

   elsif &=File2
   end
   ReturnValue = 0
   break
end

So basically this allows you to loop until you find an unfiltered record. You can even set the ReturnValue to a non-zero value to stop the processing of the current file completely.

The Report Previewer

As can be seen on the Global General Tab, it is possible to choose a previewer for your generated reports besides the default RightReports or ABC ones. The way to go about using such a 3rdparty previewer depends on the product, but the general idea is as follows:

• Add the Global Extension for the specific 3rdparty reporting tool who's previewer you want to use
• Select the desired previewing tool on the Global General Tab, under Previewer.
• There will possibly appear a new tab on the RightReports global extension, next to the General Tab - fill in the neccesary details here.

At the moment RightReports supports the IceTips, CPCS, RPM, ABC and RightReports-built-in report previewers. It is also possible to handcode your own call to a previewer, should you wish to choose that option. If you have any other previewers you would like to see included in our hardcoded list, please do not hesitate to contact us at support@capesoft.com.

The RightReportsPrint Procedure

RightReportsPrint is the procedure responsible for printing the report created by the report editor. At the moment, the RightReportsPrint procedure is imported as a source procedure and the code is hence available to you as a programmer. It is recommended that the majority of the code be left alone. There are, however, certain situations in which you may want to edit the code.

For example, you want to use your own Report Previewer. In this case, you could hand-code the call to the previewer yourself. Choose the Handcode option on the General Tab of the Global Extention, and follow the instructions layed out on the Handcoded Previewer tab that appears. Alternatively, you can do a search in the RightReportsPrint procedure for RightReportsPreview. You can replace this function call with your own.

Printing to a PDF File

As you saw on the RightReportsPrint Window, you can choose to output your report to a number of formats. One possibility is to ouput to PDF. To enable this, you need to take the following steps:

• Make sure you have abprpdf.inc and abprpdf.clw somewhere in your path. This class ships with Clarion 6 Enterprise Edition, but not with Proffessional edition.
• Go to the Global General Tabon the RightReports Global Extention, tick the Enable printing to PDF checkbox.

Printing to Word and Excel

As was mentioned before, it is possible to output to a number of differrent formats. Among these is the possibility to send the report output to a Microsoft Office Excel or Word file. Note that you need CapeSoft Office Inside version 2.63 or later. To enable this feature you need to take the following steps:

• Add the Office Inside Global Extention to your application.
• Note: If you are using Legacy, you need to enable the "Enable the use of ABC classes" checkbox on the Classes Tab of the Global Properties of your app.

Importing and Exporting a RightReports Report

It is possible for you to export a Report from RightReports into an XML format, and to import such a report again too. The idea here is to make reports portable. For example, this feature enables you to export a report, send the resulting XML file to a client, and he or she can then import the report into their system with minimal fuss. In addition, by exporting a report, you ensure that you have a saved copy in case you need to revert back to it for whatever reason. Re-importing an exported report also mimics the copy-paste action.

Note that this feature requires require XFiles 1.61 or later. To enable this feature, you need to take the following steps:

• Import the RRImportExportABC.txa (or ImportExportLegacy.txa) file into your application
• Add the global xFiles extention to your application.
• The RightReportsImport and RightReportsExport procedures each has a RightReports Extension that generates the neccesary code. They look something like this:

There is one option allowing to to control which reports may be imported into your program. If an exported report does not have this identifier, importing it will fail. The idea is that programs with differrent dictionaries will clearly not be able to support the same reports. Hence, using the dictionary name here seems like a good idea.

Importing Reports from a TXR File

RightReports can import reports that were created using Clarion's Report Writer with ease. To enable this feature, you need to take the following steps:

• The RightReportsImportTXR procedure is imported when you import the RightReportsFunctions.txa file.
• You just need to call this procedure from an applicable place in your application.

This procedure merely opens a window asking the user to specify the relevant TXR file before importing all the reports in that TXR into the RightReports report database. These reports then become available in the RightReportsBrowse, and can be edited and printed as usuall RightReports reports from this point on.

Question Summary

• I imported the RightReportsFunctions TXA and received a whole lot of hyperactive errors.
• When opening the report Editor, I get a number of errors that are long the lines of "No connection string found for dbo.rrdefnfiles". It seems to happen for all the imported RightReports tables.
• Tips for using File Manager 3 (or File Manager 2) and RightReports in your application
• When I open my app, I get an "Unknown Template Type (EditInPlace) " type error.
• After closing and reopening the app, the image filename is still in the properties but no image is displayed in the designer or on the preview or printed on the report. If I reselect the image file in the designer, then it appears again.
• I have a file that I want to use as a secondary loop that is not related to the primary file in the dictionary explicitly.
• I have a report that reports on the Clockings file. I want some users to not have access to certain records in the Clockings file when printing the report, i.e. I want certain records to be omitted from the report for certain users. How do I do this?
• How do I incorporate RightReports table changes into my dictionary?
• I want to group certain reports together and only display a given group in the reports browse.
• Since we have thousands of fields and over 220 tables, looking at field descriptions one at a time is too slow. I need to get at the field queue and change the description just after the field queue is built.
• Change the file queue description to contain both field name and field description. That way you can see the description of the filed as you scroll down the list. Rather than having to stop at each field to look.

Answers

• I imported the RightReportsFunctions TXA and received a whole lot of hyperactive errors. Add the hyperactive control template to the RightReportsPrint procedure. You will also only get this error if you have ticked the Use HyperActive to Preview PDF Files option on the Global Extention.

• When opening the report Editor, I get a number of errors that are long the lines of "No connection string found for dbo.rrdefnfiles". It seems to happen for all the imported RightReports tables. The problem is more than likely that you are using an SQL backend and you have not filled in the Owner fields of the RightReports tables.

• Tips for using File Manager 3 (or File Manager 2) and RightReports in your application. If you are making use of FM2 or FM3 in your application, you must not forget to add the Version option to each of the imported RightReports tables on (right-click on the table, choose Properties, go to the Options Tab and enter an option called Version set to the value 1).

• When I open my app, I get an "Unknown Template Type (EditInPlace) " type error. To fix this, go to "Template Registry" under the Setup Menu and register editin.tpl in clarionx\3rdparty\template. Reopen and recompile your app.

• After closing and reopening the app, the image filename is still in the properties but no image is displayed in the designer or on the preview or printed on the report. If I reselect the image file in the designer, then it appears again. For the moment, RightReports does ot save the path of the image, so your image has to be in your application directory.

• I have a file that I want to use as a secondary loop that is not related to the primary file in the dictionary explicitly. The happy news is that this is entirely possible using a simple trick. What you do is for the parent file of the secondary loop, choose "None". Then just enter a filter for this secondary loop that describes the relationship between the primary file and this secondary file. For example, suppose you had a Customers file and an Invoice file in the dictionary that werent related, but the Invoice file had a CustomerNumber field. Then you would enter for the filter something along the lines of: "INV:CustomerNumber = CUS:RecordNumber".

• I have a report that reports on the Clockings file. I want some users to not have access to certain records in the Clockings file when printing the report, i.e. I want certain records to be omitted from the report for certain users. How do I do this? See the Section on Preventing Access to Table Records.

• How do I incorporate RightReports table changes into my dictionary? You can either make the changes yourself in the RightReports tables in your dictionary, or take the below steps. Either way, dont forget to up the version number if you are using FM3.
  • Delete the RR tables from your dictionary.
  • Re-import the RightReportsTables.TXD file.
  • Open your Application.
  • Re-Import the RightReportsFunctionsABC.txa (or RightReportsFunctionsLegacy.txa) file
  • Go to the Global Extentions
  • Take a look at each of the table tabs. Some of the fields may have dissappeared and you will need to re-enter them. Alternatively, you can just remove the global extention and add it again, making sure to remember what your previous settings were.

• I want to group certain reports together and only display a given group in the reports browse. You can use the ReportType property to assign a group number to each report. You can then filter the RightReportsBrowse according to this ReportType field.

• Since we have thousands of fields and over 220 tables, looking at field descriptions one at a time is too slow. I need to get at the field queue and change the description just after the field queue is built. You can embed code after the queue was built to edit the field descriptions yourself. The embed point is called "End of BuildFilesQ Routine" and is at the end of the BuildFilesQ routine. The RRFilesQ definition is as follows:

  rrFilesQ              QUEUE,PRE(), THREAD
  rrFileQ:Display         STRING(40)
  rrFileQ:Level           LONG
  rrFileQ:FileName        STRING(40)
  rrFileQ:FieldName       STRING(40)
  rrFileQ:FieldDetails    STRING(256)
                        END

  The field and table names are stored in the rrfileq:Display field, the field names in rrFileQ:FieldName, and the table name in rrFileQ:FileName. The field descriptions are stored in rrFileQ:FieldDetails. You would hence probably want to do a fetch based on rrFileQ:FileName or rrFileQ:FileName, and edit the rrFileQ:Display and rrFileQ:FieldDetails properties to suit your needs.

• I need to change the file queue description to contain both field name and field description. That way you can see the description of the field as you scroll down the list, rather than having to stop at each field to look. The FilesQ is displayed in an ordinary listbox on the RightReportsUpdate window. You can hence set up this listbox in the Clarion window editor as you would like it. See the question on editing the field descriptions on above for more information on how to work with the queue that populates the listbox.

This template is copyright © 2007-2007 by CapeSoft Software (Pty) Ltd. None of the included files may be distributed. Your programs which use RightReports can be distributed without any RightReports royalties.

Each developer needs his own license to use RightReports (need to buy more licenses?).

This product is provided as-is. Use it entirely at your own risk. Use of this product implies your acceptance of this, along with the recognition of copyright stated above. In no way will CapeSoft Software (Pty) Ltd, their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

To download the latest version of CapeSoft RightReports please visit http://www.capesoft.com/RightReportsd.htm. To purchase CapeSoft RightReports, please click on the ClarionShop links below.

Buy
	Web www.capesoft.com Email: support@capesoft.com Telephone: +27 21 715 4000 Fax: +27 21 715 4000 Post: PO Box 511, Plumstead, 7801, Cape Town, South Africa www.clarionshop.com

Version 1.08 beta - 24 April 2008

• Took out the stops in the RightReportsUpdate procedure
• Added some resizing code to the RightReportsUpdate procedure. This is template-generated code. Just make sure that you have disabled the "Save and Retore Window Position" option on the procedure properties.
• Added a new window to the editor allowing users to select the appropriate screen picture. It is called RightReportsLookupPic. So additions were made to the RightReportsUpdate window to ensure that the EditInPlace template calles this procedure when neccesary. So you will need to re-import this window, or add these changes to the window manually. You need to Import RightReportsFunctionsABC.txa (or RightReportsFunctionsLegacy.txa) to obtain this LooupPic window too.
• Also added a new RightReportsEditFormula window, which is once again called to edit any formulae in the RightReportsUpdate window. Steps to be taken here are the same as for RightReportsLookupPic above.
• Some updates to the docs were made.
• Descending keys now work for primary and secondary loops too.

Version 1.07 beta - 16 April 2008

• Note that you need the latest version of Draw (version 2.62 or later) for this version of RightReports. Otherwise you will get errors regarding the FitWidth, FitHeight and Clipped fields.
• Made the following changes to the RightReports tables (see the FAQ on Dictionary Changes on how to incorporate these):
  • Changed the length of the following fields in RRDefinition
    • RRDFN:ReportOrder to 256
    • RRDFN:Description to 256
    • RRDFN:PraimryFIle to 256
    • RRDFN:To1, RRDFN:To2, RRDFN:To3 to 100
    • RRDFN:From1, RRDFN:From2, RRDFN:From3 to 100
    • RRDFN:FontName to 256
  • Made the following changes in RRDefnFiles:
    • RRDFI:Name length to 256
    • RRDFI:ParentFile length to 256
    • RRDFI:KeyName length to 1024
    • Added the following key: RRDFI:EntryTypeKey (ascending on DefnCode and EntryType fields)
  • Made the following changes to RRDefnBandControls (inside the PropertiesGroup)
    • Added RRDBC:FitWidth         long
    • Added RRDBC:FItHeight       long
    • RRDBC:TextValue length to 1024
  • Changed the folloing field lengths in RRDefnCalc
    • RRDFC:FieldName to 100
    • RRDFC:ElseFieldName to 100
  • Changed the folling field lengths in RRDefnSecond
    • RRDFS:FromValue1, RRDFS:FromValue2, RRDFS:FromValue3 to 100
    • RRDFS:ToValue1, RRDFS:ToValue2, RRDFS:ToValue3 to 100
  • Changed the following field lengths in RRDefnFields
    • RRDFL:Name to 100
  • Changed the following field lengths in RRDefnTotal
    • RRDTL:Name to 100
    • RRDTL:TotalName to 100
• Fixed some bug relating to the font colour in the editor
• Added code allowing you to export to Excel. You need Office Inside for this though. See the section on Exporting to Word and Excel.
• Added some code to enable the SQL filter.
• Added the ReportType property to the Report editor. The user can use this field if he has several types of reports he wants to group together.
• Major changes to the ImportTXR procedure. It should be working much better now.
• Added a prompt column to the local and global variables tab. Allows you to enter the prompts for use variables here.
• Changed the Report Structure List sothat the header and footer always appears at the top and bottom of this list respectively.
• Primary file's range prompts can now be edited successfully .
• The Legacy parent file editor did not work.
• Got rid of the flickering on the Print window.
• Added the FitWidth and FitHeight properties. In particular, you can set FitWidth to ensure that a string control gets adjusted to the length of its contents when the report gets printed.
• Added the Linking Fields property to Lookups that have no parent files. Basically, this allows you to do a lookup based on a custom relationship between files.

Version 1.06 beta - 29 February 2008

• For ImportTXR, imported user variables now have prompts assigned to them
• Set a default sort order in the report browse for mysql applications
• Had problems with MySQL so had to rename a number of the table fields - all Order, Type and Condition fields.  So you will need to re-import the RightReports tables, and remove and re-add the global template. This will unfortunately mean you need to re-import the RightReportsFunctions.TXA file too. Alternatively, you can change the fields directly in the dictionary. Here are the changed fields:

• RRDFN:Type became RRDFN:ReportType
• RRDFN:Order became RRDFN:ReportOrder
• RRDFB:Condition became RRDFB:BandCondition
• RRDBC:Type became RRDBC:ControlType
• RRDFC:Condition became RRDFC:CalcCondition
• RRDFL:Condition became RRDFC:FieldCondition
• RRDFL:Type became RRDFL:FieldType
• RRDFL:Order became RRDFL:FieldOrder