report writer-v8

ProvideXVERSION 8.0

Introduction 3

System Requirements 4

Designing a Report 5

Generating a Report 35

Designer Options 43

Object-Oriented Interface 45

Report Writer User Interfaces 95

Report Writer

ProvideX is a trademark of Sage Software Canada Ltd.All other products referred to in this document are trademarks or registered trademarks of their respective trademark holders.

©2007 Sage Software Canada Ltd. — Printed in Canada8920 Woodbine Ave. Suite 400, Markham, Ontario, Canada L3R 9W9

All rights reserved. Reproduction in whole or in part without permission is prohibited.

The capabilities, system requirements and/or compatibility with third-party products described herein are subject to change without notice. Refer to our website www.pvx.com for current information.

Publication Release: V8.0

ProvideX V8.0 3 Back

The Report Writer

Int roduction

The Report Writer is a ProvideX add-on for designing and generating reports. Both the application designer and the end-user can create and manipulate the contents of a report with the ease and functionality of a spreadsheet application. Features include data drag and drop, column and row sizing, computational values, cell formatting (fonts/colours/borders/alignment), image support, sorting rules, control break groupings, data filters, and run-time parameter settings.

Input sources can be any native ProvideX file with an embedded data dictionary, a ProvideX View, or any other data source whose data can be accessed using a Custom Data Source Object. Output can be channelled to a printer or PDF file, the ProvideX Viewer, the Windows clipboard, an HTML file, or a user-defined output object.

As well, the system designer can use the pvxreport object interface to control virtually every aspect of generating a report, from changing report attributes on the fly, to altering data values before they are displayed.

Report DesignerThe Report Designer is the user interface for designing the layout of the report. The data is defined in terms of data source selection, sorting rules, and selection criteria for filtering the data. Report layouts are saved as ProvideX report definition files, which are used to generate the reports. See Designing a Report, p.5.

Generating a ReportA report can be generated from within the designer interface itself, or via a special ProvideX program that can be invoked as a lead program or called from another program. The RunReport( ) method of the pvxreport object interface can also be used to generate a report. See Generating a Report, p.35.

Multilingual CapabilityAll text messages used in the designer interface and run-time displays are derived from the *msglib.xx message library, so there is full multilingual capability.

Report Writer


System Requirements

All the Report Writer features described in this manual require Version 8.0 or higher. The Report Designer component is available as part of the ProvideX Professional or eCommerce bundles. As with previous versions, it can also be purchased as an add-on package with activation 20012 or on a per-user or per-site basis; however, the report generation facilities and pvxreport object interface can be run under a base ProvideX activation.

The Report Designer also uses the NOMADS graphical user interface, and is not suitable for character-based systems.

Note: Contact your dealer/distributor or visit the ProvideX website at www.pvx.com for the latest information on product options and licensing.

Report Writer Designing a Report


Designing a Report BMK

D es igning a Report

Report definitions are created via the Report Designer. This user interface can be accessed through the NOMADS Utilities menu, or by typing RW (for Report Writer) at the command prompt. It can also be made available to end-users (within an application) using the PROCESS directive:

PROCESS "Design","*rpt/rpt.en"

To update a specific report, the report definition file can be included as an argument:

RW myreport.pvr or PROCESS "Design","*rpt/rpt.en","myreport.pvr"

You can also update a specific report from within the Report Designer interface by selecting Open from the File menu, clicking the Open File button on the toolbar, using the file browser, or selecting a file from the file history list in the File menu.

The Report Designer interface can be used to define the source of the data, design the layout, save the definition so it can be used to generate a report, and then generate the report. The first three aspects of the Report Designer are covered in the sections below. Because there are several ways to generate a report, the final point will be discussed under the separate heading Generating a Report, p.35.

Defining the Data, p.6Creating the Report Layout, p.13Report Options, p.30Setting the Report Destination, p.33Saving the Report Definition, p.34Testing the Report, p.34Deleting Report Definitions, p.34

Topics



Defining the Data

The data being used in the report must be defined in terms of input source selection, sort sequence, and selection criteria (for filtering the data). Data may also be derived in the form of external parameter values supplied at run time. These aspects are defined via the Report Designer’s Data menu.

Input Source, p.6Sort Sequence, p.7Calculated Fields, p.8Parameters, p.10Data Filters, p.11

Input SourceTo determine the source of the data to be displayed in the report, select Input Source from the Data menu. The input source can be any native ProvideX file with an embedded data dictionary, a ProvideX View, or any other data source whose data can be accessed using a Custom Data Source Object. External databases such as ODBC, Oracle, or DB2, may also be accessed via Views.

Select the input source type:

Once an input source is selected, its elements and their descriptions appear in the data items list of the Report Designer, ready to drag and drop into place on the report layout.

If you wish to change the input source, a warning will be displayed apprising you that data elements, sort sequence, filters and data groupings may no longer be valid. You may choose to ignore this warning, or clear the selected items.

Topics

Note: If a report requires data from multiple related files, use a View as the input source. Refer to The Views System documentation for more information.

Table Name Identify an input table using its logical table name as defined in Data Dictionary Maintenance.

File Path Select a file using its physical pathname.

View Select a View from the presented list. Direct access to View Maintenance may also be available, allowing you to update and create Views. To suppress the View Maintenance option, set the %RW_Suppress_View_Maintenance global variable to a non-zero numeric value. For details on Views, refer to the The Views System documentation.

Source Object Enter the name of the source object, and an argument to identify the input source. The source object must adhere to the Custom Data Source Objects interface standard described in The Views System documentation.



A report can be defined with no data source selected. The output will consist of one page with a page header, report summary and a page footer.

Sort SequenceAfter the input source is selected, it is necessary to set the sort sequence for the data. Select Sort Sequence from the Data menu. The default for ProvideX files and Views is to sort using the primary key.

There are two ways to define the sort sequence. Select Pre-defined Sort to sort the data based on one of the file's internal key structures (i.e., built-in key), or create a Custom Sort sequence comprised of up to sixteen table elements in ascending or descending order. Custom sort elements can also be defined as case-insensitive to ensure that upper and lower case letters are sorted together.

The grouping of data to be used in the report is a major consideration when determining a sort sequence. For example, if the data is to be grouped by department, and then by each manager within the department, then the sort sequence must be by department first, then by manager.

If you create groupings based on your sort selection, but decide to change the sort later, the Report Designer will attempt to remap the groupings to the new sequence. You may choose to make the changes, clear the current groupings, or cancel the new sort order.

Note: Pre-defined sort sequences are processed faster than custom sort sequences.



Calculated FieldsCalculated Fields are virtual fields derived from expressions created using data source elements and other calculated fields. A calculated field can also be a translation field that has different values based on conditions; e.g., a translation field can have the values "Yes" and "No" depending on the value of a Boolean variable.

A name is associated with the calculated field, and the value is evaluated and stored in the named variable after every data record is read. Calcluated fields can be used wherever data elements are used within a report definition, including formulas, filter definitions, group functions, and custom sort orders. To create calculated fields for a report, select Calculated Fields from the Data menu.

A calculated field definition is comprised of the following:

Name The name of the data variable in which to store the result when the expression is evaluated. It must start with an alpha character, followed by alphanumeric characters, underscore or period. Maximum 30 characters.

Description Short description of the calculated field (optional).Type Text or numeric (computational) value.Maximum Length The maximum length of the value to be stored. If numeric, the

length may contain a scaling factor (e.g., 10.2 where total length is 10 with two digits to the right of the decimal).

Function Select Formula or Translation, depending on whether you wish to define a formula or a translation field.

Transfer Button Transfer to the expression or translation field definition area below the main list.



The formula or set of translation values associated with the currently selected calculated field appears in a work area below the list of calculated fields. If Formula is selected as the function, then an input box is displayed in which to enter the ProvideX expression to be evaluated and stored in the named variable. A tool button to the right of the input box gives you access to a more user-friendly interface for building the formula. If Translation is selected, then you must define all the possible translation values for the translation field and the conditions associated with them.

When defining a translation field, there is initially a single line for the default translation value. Click on the button to add more values. Each translation value has a condition associated with it (except the default value) to determine when that value is to be used. If none of the conditions are true, then the default value is used. To define a condition, click on the button in the first column to invoke the standard filter definition interface. The translation value itself can be a fixed value or expression. If the value is fixed, just type the literal value into the Translation Value column of the grid. If it is an expression, check the box in the Exp column. When you do this, a tool button will appear in the column to the right of the Translation Value column. You can press this button to access a user-friendly interface for defining an expression, or you can just type the ProvideX expression. At run-time, the conditions associated with the translation values are evaluated in the order they appear, so order is significant. Use the and buttons to alter the order. Note that the Default item will always be last and cannot be moved.

The order in which calculated fields appear in the definition list is significant as it reflects the order in which fields are evaluated. This is important when a calculated field contains a reference to another calculated field because the reference field would have to be evaluated first. Buttons for changing the list sequence are located beside the list.

Once calculated fields have been defined, they will appear in the data pane of the Report Designer, directly below the data source and its elements. From here, they may be dragged and dropped onto the report definition.

They will also appear in element lists found in the Sort Order, Group Functions, Filters, and Numeric & String Formula build interfaces.



If an error occurs while evaluating a calculated field during report execution, default values (0 for numeric and null for string) are assigned to the field and a Report Writer system variable called the Calculation Error Flag (_CalcErrorFlag) is set to 1. This variable is available in the System list in the Designer data pane.

ParametersParameters are values that are supplied by the user or application program when a report is generated. These may be displayed in the report, used in formulas, or used to set up selection criteria. For example, a report may be designed to generate data for a particular department, to be specified by the user requesting the report. Also, a report may be designed to display transactions between a certain start and end date to be specified at run-time. To set up parameters, select Parameters from the Data menu.



A parameter definition is comprised of the following:

By default, when the report is generated, a generic interactive parameter interface is presented to the user to input the values required for the report generator if parameters are defined.

These values are validated for correct type, length, and minimum/maximum lengths; however, this may not be sufficient to catch all invalid entries. Be mindful when creating prompts, so that the required input is described as thoroughly as possible. Invalid parameter values can result in unexpected data or empty reports.

It is also possible to create your own interface to input parameter values, which can then be passed to the report generator at run-time. Parameters can be set programmatically using the Report Writer object (*rpt/pvxreport), or passed as panel or program arguments by setting the Parameter Interface report option. See Custom Interfaces, p.32.

Data FiltersSelection criteria may be set up to filter the data for the report. Select Filters from the Data menu to define the data filters.

Data is filtered based on filter sets. A filter set consists of one or more conditions, all of which must be true for the filter set to be true. For each filter set, select any conditions you wish to apply for each table element to be used in the filter.

Parameter Name The name of the data variable. It is used mainly in formulas and filter definitions and must start with an alpha character, followed by alphanumeric characters, underscore or period. Maximum 30 characters.

Prompt/Description Prompt to be displayed in the user interface which is presented when the report is generated. This should explain to the user what value to enter and its format.

Type Text or numeric (computational) value.

Maximum Length The maximum length of the value to be entered by the user.

Minimum Value The minimum value that can be entered. (optional)

Maximum Value The maximum value that can be entered. (optional)

Default Value Pre-set value that will automatically be loaded. (optional)



The Condition options include:

Indicate whether the filter condition is to be Case Sensitive and enter any value(s) to be used in comparisons. Comparison values may be selected from a set of options consisting of formulas, parameters, or other table elements — or fixed text/numeric values can also be entered.

A filter set also includes an option to accept or reject a data record based on the outcome of its conditions.

If a filter set is evaluated as not true, then the next set is evaluated (and the next) until a set is evaluated as true, at which point the associated option determines whether the record is accepted or rejected. Up to 8 filter sets may be defined. If no filter sets are found to be true, then the inverse of the last filter set option determines if the record is accepted or rejected.

Example 1:

Set 1 Accept CustNum Between 1000 and 1999 inclusiveSet 2 Accept CustNum Between 4000 and 4999 inclusive

None

Equal to <Value1> Between <Value1> and <Value2> inclusive

Not equal to <Value1> Between <Value1> and <Value2> exclusive

Less than <Value1> Any of <Value1>, <Value2>, <Value3>, …

Greater than <Value1> None of <Value1>, <Value2>, <Value3>, …

Less than or equal to <Value1> Contains <Value1>

Greater than or equal to <Value1> Starts with <Value1>



These filter sets would be used to process records from 1000 to 1999 and 4000 to 4999.

Example 2:

Set 1 Accept Type$ Equal to "A"Amount Greater than 1000

Set 2 Accept Type$ Equal to "B"Amount Greater than 2000

Reject Type$ Equal to "C"Reject Amount Less than 5000

The above filter sets will process all "A" records with Amount > 1000, all "B" records with Amount > 2000, reject all "C" records or records with Amount < 5000.

To add or remove sets, press the "+" or "-" buttons in the Filter Set area. The Back/Next button set can be used to navigate through the filter set definitions. New filter sets will be added at the end; however, the Move Up and Move Down buttons can be used to arrange the order in which the filter sets will be evaluated.

When a report is generated, if a report has one filter set with an 'Accept' option, the filters are analyzed to determine if minimum/maximum values can be applied to the sort sequence of reports using pre-defined sorts. These can be used to optimize the data retrieval process. In the case of custom sort sequences, an attempt is made to map the sort to an existing internal key so the same optimization may be used.

Creating the Report LayoutOnce the data source is established, the contents and apperance of the report may be specified.

Report Sections, p.13Report Header / Trailer, p.14Grouping the Data, p.15Conditional Detail Groups, p.17Filler Line, p.18Group Functions, p.20Editing the Layout, p.20Selecting Report Elements, p.22Formatting, p.26Conditional Cell Definition, p.28Page Setup, p.29

Report SectionsBy default, the report’s layout is composed of four sections:

Topics

Page Header Printed at the top of each page.Detail Line Printed once per record.Report Summary Printed once at the end of the report.Page Footer Printed at the bottom of each page.



The lines beneath each section heading are printed whenever the section is printed. If you do not wish to print anything for a particular section, simply remove the lines under it.

Report Header / TrailerA report can also optionally have report header and report trailer sections. A report header is printed once at the beginning of the report. It can be used to output such things as a title page, and opening message, etc. The report trailer is printed once at the end of the report, and can be used to output a closing message, blank page, etc.

To add a header or trailer to a report, select the Group item from the Edit menu, or click on the > cell next to a section line in the left-most column of the report layout. Then, select the Report Header/Trailer tab. To add a report header or trailer, check the appropriate box.

If a Report Header or Report Trailer is selected, there is an option to print the header or trailer on a separate page. If this option is selected, then further options are available allowing you to specify whether to include a page header and footer, or to centre the page contents vertically. In the case of the header, there are additional options to output a blank page after the header (for duplex printing) and to include the header page in the page count. The trailer also has an option to be output only if the page count is uneven (for duplex printing). If a trailer is not printed on a separate



page and a filler section is defined, there is an option to use a filler line to fill the gap between the last line and page bottom. (See Filler Line, p.18) When a header or trailer is added to a report, the new section will be added to the Report Designer layout below the Page Footer section.

If the output destination does not support pagination (such as the clipboard and HTML output), then the header and/or trailer will be output as if the Use separate page option had not been selected.

Grouping the DataData can also include logical data groupings based on sort sequence. Whenever a value in the sort sequence changes, this marks the end of one data group, and the beginning of the next. This is also known as a control break. For example, if an input source is sorted by company and departments, then the data may be grouped by company, with each department as a sub-group. Each group level can have associated group functions to calculate counts, totals, averages, minimums and maximums. As well, each group can have its own header and footer lines defined.

To create groups, select the Group item from the Edit menu, or click on the > cell next to a section line in the left most column of the layout.

• Add a new group by pressing Add.• Update an existing group by selecting a group and pressing Properties.• Delete a group by selecting a group and pressing Remove.

When adding groups, start with a group level 01 (based on the first element in the sort sequence), then add other groupings in sequential order.

Note: If the sort sequence does not match the groupings you need, you will have to redefine the sequence to reflect your groups.



You cannot skip groups; if you do not want headers/footers for a particular group, you can later remove the lines from that section of the report.

Options for displaying group headers include starting a new page for each new group, resetting the current page number to 1 (whenever the group changes), and forcing header lines to be printed at the top of each page. Options for group footers include forcing the group footer to be displayed at the bottom of the page, and causing a filler line to be output between the last line of the control break footer and the bottom of the page (if the control break footer is the last section to be output to a page.) See Filler Line, p.18. When groups have been added, the layout will be updated with header and footer sections for the new groups, highlighted in green.



Conditional Detail GroupsMultiple detail line groups can be defined. The additional detail groups will have conditions associated with them to determine which group will be used to display the contents of a record. For example, if a record has a TYPE$ field, then the user could define a detail line group for each possible TYPE$ value. The first detail line group is the default group. It has no conditions associated with it, and is used if the conditions for the other detail groups are not met. A maximum of 8 additional detail groups can be defined.

Press the Detail Line Groups tab to add, update or remove detail line groups.

• Add a new group by pressing Add.

• Update an existing group by selecting a group and pressing Properties.

• Delete a group by selecting a group and pressing Remove.

• The sequence in which the conditions for each group are tested can be controlled by adjusting their order with the Move Up/Move Down buttons. (Note: Detail Group 1 is the default group, and cannot be updated, removed or moved.)

When a group is added or updated, the conditions associated with the group are set. Conditions are assigned using the Define Filters panel, using the same filtering mechanism as described under Data Filters, p.11, with the exception that a detail group is being accepted / rejected rather than data.

The Detail Line Groups tab also has an option to use a filler line to fill the gap between the last detail line on a page and the page bottom. See Filler Line, p.18.



Multiple Detail Line Groups will be shown in the Report Designer as separate sections with yellow section headers:

Filler LineA filler line is a single line that is used to fill the space between the last detail, group footer or summary line printed and the page footer (or page bottom). It allows column formats (lines, background colours, etc.) to be extended to the bottom of the page. In the images below, the report on the left does not have a filler line, while the one on the right does:



The filler line fills the gap by printing a single line whose vertical height is stretched from the bottom of the last printed line to either the top of the page footer or the bottom of the page if no page footer is defined.

To add a filler line, check the Include Filler line section at the bottom of the Groups panel.

This will add a filler section to the Designer grid immediately before the page footer.

It will automatically set the filler option for all currently-defined control breaks and detail lines. The filler option can be removed from individual control breaks by de-selecting the option from the group Properties definition (see Grouping the Data, p.15), and from the detail line section by de-selecting the option at the bottom of the Detail Line Groups tab (see Conditional Detail Groups, p.17).



Group FunctionsGroup functions are calculated values that can be applied at a group level (i.e., counts, totals, averages, minimums and maximums). For example, if the data is grouped by company and department, the Sum function can be used to calculate company totals as well as department totals, etc.

Group functions are defined through the Groups interface, as described earlier. Press the Group Function tab to access the definition. Group functions are defined in terms of their function (i.e., sum, average, etc.), as well as the data element to be used in the calculation.

A format display mask will be assigned to the function, but this may be altered for the individual function, or the default may be changed in Designer Options. Once defined, group functions will appear in the list of available data items, on the left of the Report Designer interface.

Editing the LayoutThe Edit menu provides functions for editing the report layout. These functions, (except for Clear Area) can be selected as icons from the Report Designer toolbar:

Cut Copy contents, format (font, colour, alignment, etc.) and conditions associated with the selected cells, then clear the content of the selected cells and restore them to default format. Selected cells must be contiguous and must be in the same grouping of lines; i.e., selected cells may not cross a section header.



To facilitate editing, it is possible to select entire lines and columns for processing. Click on the row header area at the left of the Designer grid (where the ruler marks are located) to select all columns in a row up to the last column currently used in the report. This does not apply to Group section head lines.

To select an entire column (excluding section headers), click on the the column header area at the top of the Designer grid. Section headers are highlighted if the first column is selected, although they are not included.

Copy Copy contents, format (font, colour, alignment, etc.) and conditions associated with the selected cells. Selected cells must be contiguous and must be in the same grouping of lines; i.e., selected cells may not cross a section header.

Paste Paste cell contents, format, and conditions beginning at the current cell location, and add lines/columns to the section if required to contain all the elements being copied. If pasted cells contain merged rows or columns, joins will be included only if they are self-contained and do not extend beyond the scope of the cells being pasted.

Cells that contain group functions can only be pasted into detail lines and group footers, where the function will be converted to the appropriate group level. They cannot be pasted into page or group headers or the page footer; a warning message will be displayed and the receiving cell left blank.Line heights will not be affected by the height of the pasted lines.

Clear Area Clear all data from the highlighted cells. This function also resets the cell formatting to default settings. This differs from selecting cells and pressing Delete, which only clears the data.

Insert Line Insert a line below the current line.

Delete Line Delete the current line.

Insert Column Insert a column to the right of the current column.

Delete Column Delete the current column.

Find Text Find the specified text value in the layout. Find Text will search data items, formulas and fixed text within the cells.

Note: Cut/Copy/Paste features are internal only; i.e., they do not use the Windows clipboard.

Note: Joined cells will only be included if the column/row being selected is the first column/row in the join.



To select all, click on the top left header cell. You an also right-click on the header cells to select the row/column as well as invoke a pop-up menu with applicable editing and formatting options.

Selecting Report ElementsThe report layout is created by selecting elements from the list on the left side of the Designer interface, and then dragging them over to the layout area on the right side.

Whenever an item from the list is dropped on a cell, a formatting mask is displayed in the cell, and a red tick mark is drawn in the bottom left corner to indicate that this is a placeholder for a data element. Floating tips identify each of the items.

Select the cell to display, and edit, the underlying data variable.

The list comprises four data types types:



System Values. These are values generated by the Report Writer engine at the time a report is generated. They include such things as page numbers, the date, time, etc..

Besides these standard system values, additional user-defined values may be included using methods provided by the Logic Object Interface, p.95

Input Source Elements. These are the items or fields that make up the input source table. They are loaded into the item list when the input source is selected, and appear under the input source's name. See Input Source, p.6.

Calculated Fields. If the user has defined any calculated fields, these will be listed in the item list. See Calculated Fields, p.8.

Parameters. If the user has defined run-time parameters, these will be listed in the item list. See Parameters, p.10

Group Functions. If the user has defined group functions, these will be listed in the item list. See Group Functions, p.20. Since they contain summary information, group functions may not be placed in header sections of the layout. When dropped into a group section of the layout, the resulting data variable will automatically apply to that group level.

Formulas. To add a formula, highlight a cell, then select Formula from the Format menu. There are two types of formulas that may be defined: numeric calculations and text manipulation. In both cases, the formula may be entered as a free-form ProvideX expression.

System Value Data Variable DescriptionDate (DD/MM/YY) _DateDDMMYY$

Current date in specified formatDate (MM/DD/YY) _DateMMDDYY$

Date (DD/MM/YYYY) _DateDDMMYYYY$

Date (MM/DD/YYYY) _DateMMDDYYYY$

Date (YYYY/MM/DD) _DateYYYYMMDD$

Page _PAGE$ Current page numberDate (Default) _DateDefault$ Current date in default formatDay of week _DayOfWeek$ Abbreviated week day nameTime _Time$ Current time HH:MM amTime24 _Time24$ 24 hour time HH:MMUser name _UserName$ UIDNetwork node _NetworkNode$ NIDMachine name _MachineName$ FID(0)Calculation Error Flag _CalcErrorFlag Boolean value indicating that an error

has occurred when evaluating a calculated field

Note: Formulas, fixed text, hyperlinks and images may be added to the report layout.



To aid in the construction of an expression, press the Build button to generate the expression using a more user-friendly interface. A maximum length and the display format mask for the resulting value of the formula must be defined. Default format masks are generated based on the length; however, you can press the Define button to define an alternative mask. Formulas may also be altered by selecting a cell containing a data element.

Formulas cannot be used in group functions, custom sort definitions or other formula definitions, and have limited use in filter conditions. Also, calculation errors cannot be trapped. Use calculated fields to overcome these possible shortcomings. See Calculated Fields, p.8.

Fixed Text. Fixed text may be added by simply typing it in a cell. It has no format mask or tick mark and will appear verbatim in the report.

Hyperlinks. Hyperlinks may be included as part of reports generated with HTML output. A hyperlink is associated with a report cell. The hyperlink definition consists of a URL reference (fixed or expression) and an option to open the hyperlink in the same browser window or a new one. The report cell value will be displayed as the descriptive text for the link in the report unless an image is assigned to the cell, in which case the image will serve as the link trigger. If an expression is used for the hyperlink which evaluates to null when the report is generated, then the html output will display only the descriptive text or image, and not create an active hyperlink. Reports destined for non-html output (i.e., printer, PDF files, ProvideX Report Viewer, or clipboard) will simply display the cell value.

A cell with a hyperlink must first be assigned a value (text, data source value or formula) to be displayed as the text for the link. The hyperlink may then be added by selecting the Hyperlink item in the Format menu or the pop-up menu. The hyperlink definition interface appears as follows:

The HTML HyperLink input can contain a literal link, or a ProvideX expression, if the Expression box is checked. The drop box is pre-loaded with the names of the data source fields and report parameters. An option to Open link in a new browser window is also available; by default, the link will open in the current browser window.



Images. Images may be included as part of generated reports. They may be associated with a report cell, consisting of internal images, bitmaps, or any image type included with the ProvideX Multiple Image Type Support add-on (if activated). If images are not available at run-time, cell contents will be displayed in their place. While images are fully supported on Windows/WindX systems, under UNIX/Linux, they require use of the *PDF* channel (.jpg only).

To add/update an image, select the Image item from the Format or pop-up menu:

The Image Path can contain the path to the image, an internal bitmap reference (e.g., !Files), or a ProvideX expression, if the Expression box is checked. The drop box is pre-loaded with the names of the data source fields and report parameters.

Image paths must be defined such that they are available at run-time on the machine on which they are rendered. For example, when generating reports in a WindX environment, reports generated to the ProvideX Viewer (*VIEWER*) are rendered on the client, so the images must reside locally. The following chart shows the location of the images for the more common output destinations on WindX-based systems:

The Report Writer Designer renders reports to the above destinations locally.

Note: HTML will not support internal bitmaps; e.g., !File, and reports sent to the clipboard will not contain images, but will contain the alternate text associated with an image.

Destination Special File Name Image Location

Print Preview *VIEWER* Client

PDF Generator*PDF* Server[WDX]*PDF* Client

Windows Printer*WINPRT* Windows Host (server), UNIX/Linux Host (client)[WDX]*WINPRT* Windows Host (server), UNIX/Linux Host (N/A)

HTML File FileName.htm Server

Note: Image paths that make use of the special *BMP directory (e.g., *bmp/image.jpg) cannot be resolved in HTML output.



Display Options include:

Resize to fit regionResize with same aspect ratio, align top leftResize with same aspect ratio, centre in regionOriginal size, align top leftOriginal size, centre in region

If the cell contains a value (text, data source value or formula) as well, this value will only be displayed if the image is not available at run-time. If both an image and a hyperlink are defined for the same cell, the image will be used to trigger the hyperlink in HTML output.

FormattingColumn width, row height, and individual cell attributes can be easily adjusted in the report. Column widths are adjusted by dragging the edge of the column in the column heading area with the mouse. Similarly, row height may be adjusted by dragging the edge of the row header. Column width and row height can also be adjusted via pop-up menus that are invoked by right-clicking on column and row headers, or on individual cells. (See Designer Options to set up default column and row dimensions.) Note that when sending a report to the printer you should ensure that the total width fits on the page, otherwise the right-most columns will be truncated.

The Format menu contains a number of options for formatting cells in the report layout. These are also available as icons on the toolbar, as well as in a pop-up menu:

Note: The actual size of an image displayed using one of the Original size options is dependent on the resolution of the output device; e.g., an image displayed to the monitor using the ProvideX Viewer, will appear much larger than the same image output to a high resolution printer. One of the Resize options is recommended to maintain consistency across different types of output.

Display Format When an item is dropped on a cell, a display format mask is automatically assigned to the value. Use this option to change the assigned mask.Format masks can be fixed values or ProvideX expressions. Format mask expressions are displayed prefixed with an equal sign; e.g., =%F$. Expressions are evaluated at run-time.

Font All cells are initially set up using a default font, font size, style and orientation. Font size refers to point size; styles include normal (default), bold and italics. Orientation can be horizontal (default), vertical up (90 degrees) or vertical down (270 degrees), if supported by the particular font and output destination. (e.g., raster fonts and HTML output do not support vertical fonts.



Also note that vertical fonts cannot be displayed in the Designer grid, even though they will appear correctly in the output.)

The Font option allows you to change the font and its attributes in the selected cells. This option also allows you to change the default font. When the default font is set, all cells currently defined with the default font (in terms of font, size and style) will change to the new default. The default font settings will stay in effect until changed using this option, or an existing report definition with a different default font is loaded into the Report Writer.

The font may be selected from the list, or entered in the input box above the list. This means you can select a font for a report that is not resident on the designer's system.

See Designer Options, p.43, to set up a default font for all your reports.

Colour Set the foreground colour of the selected cells.

Background Colour

Set the background colour of the selected cells. Default is white. If a report also uses the Alternating Background Colours report option to highlight detail lines, then the background cell colour, if defined, will take precedence, unless the background colour is white. See Colours, p.31.

Alignment When an item is added to the layout, a text item will be left-justified and numeric items will be right-justified. Use this option to set alignment to left, right or centered.

Borders All borders are black. Options include:

Be aware that the proximity of the border to the values shown in a cell may, in practice, be closer than that displayed in the Report Designer.

If background colours are used in conjunction with borders, borders on the bottom or right of a cell may be overdrawn by the background colour of the cell to the right or beneath.

Border Width Adjust the border width: thin, medium or thick. The width must be set prior to adding the border. The currently-selected width is displayed on the border width button on the toolbar.

Note: If a system does not support a given font, it will be mapped to one of the more common fonts. PDF output supports a limited number of fonts. See *PDF* in the ProvideX Language Reference.

Full grid Right edge Left edge Top edge

Bottom edge Edges only Inside only No borders



Conditional Cell DefinitionAn alternate definition for individual cells may be specified within the report. The alternate cell definition has a condition associated with it to determine which definition will be used for display when the report is generated. If the specified conditions are not met, then the original cell definition is used for displaying the cell. A cell definition includes cell contents (value, image, hyperlink), display format and attributes (colours, font, alignment, wordwrap option and borders).

To create an alternate definition for a cell using the Report Designer, select a cell, then select the Alternate Cell Condition item from the Format menu or from the Popup menu. This invokes the Define Filters panel to specify the conditions under which the alternate definition will be used. Conditions are assigned using the same filtering mechanism as described in Data Filters, p.11, with the exception that a cell definition is being accepted / rejected rather than data.

Join Merge the highlighted cells. If the value in a cell spills into the next column, you should join the cells. For printed output, this may not always be necessary as the value will print outside of the cell area, but HTML output requires that such cells be joined to maintain proper column spacing. A common use of joined cells is to centre titles across several columns. Cells may be joined across columns and rows, but the rows must be in the same Section.

Unjoin Reset joined cells to individual cells.

WordWrap Wrap the cell text within the defined cell dimensions. The contents will self-wrap, or break at a line-break character ($0A$). If the contents of the cell contain other characters denoting a line break, you can substitute for them using a formula, such as SUB(text$,$09$,$0A$).

Applicable to printer/PDF/Viewer output only; HTML output wraps by default, and clipboard output is not formatted.

Bulk Edit This option gives you the ability to edit several formatting attributes in a range of cells simultaneously. Attributes that can be set include word wrap, text alignment, borders and border size, font, font style, point size and orientation, as well as text and background colours. To set an attribute for all the selected cells, choose a setting for the attribute from the drop-down list, or, in the case of font, you can enter a font name that is not in the list, thus allowing a font to be selected which may not exist on the designer's computer. Bulk Edit also has an option to Include alternate cell definitions which will update alternate cell definitions that exist within the selected cells as well.

If a single cell is selected, Bulk Edit displays all the current format settings for that cell.



When the condition is initially defined, the values, format and attributes of the original cell definition are loaded into the alternate definition, and the cell display switched to display the alternate cell definition, which can then be altered. When a cell has alternate definitions, this is signaled by a tick in the top left corner of the cell. A green tick means the main cell definition is being displayed, and a red tick signals the alternate cell definition. After the alternate cell condition has been set, selecting this option will allow the condition to be changed, but will not cause the display to be switched.

To switch between the two definitions after the condition has been set, select the Switch Cell Definition item from the Format or Popup menus. The Alternate Cell Condition and Switch Cell Definition options are also available using the pair of magenta arrows on the toolbar.

When altering the contents, format or attributes of a cell with an alternate definition, the changes will only affect the current definition, as indicated by the colour of the tick. To change both definitions, you will have to make changes to the currently displayed definition, switch the cell definition, then make the changes again. The only change that will affect all definitions is altering the default font.

Page SetupPage Setup, invoked from the File menu, allows you to set up margins and paper size as well as define orientation for reports output to the printer. There is also a Scale to fit option. Default paper size uses the current default paper size of the printer. Default margins are one-half inch at top and bottom, with the report data centered horizontally. Custom margins may be set for the left, top, right and bottom.

Orientation options are portrait and landscape.

Note: Take care to set margins that are wide enough to avoid the no-print zone that many printers impose at the edge of the page.



The Scale to fit option causes the column width, line height and font size to be adjusted either up or down so that the report will fit the page size. If margins are defined, they will be maintained. If margins are not defined, a ½ inch margin will be used as default. When selecting this option, be sure to select fonts that scale well.

Report Options

Report options are accessible through the Options item on the Report Designer menu, or via the Options button on the toolbar.

General OptionsThe following options appear under the General tab:

Suppress empty reports

If there is no data for a report, output nothing to the printer or clipboard. (Viewer, PDF and HTML output will display a blank page.) Default is to print the page header and footer of an empty report.

Bookmark PDF output when group changes

Generates a bookmark in PDF output whenever a defined control break (data grouping change) occurs within the report. This also generates a bookmark for the Report Summary, if one is defined. The text of the bookmark is based on the data source values that defined the data grouping for the control break.

Paginate HTML output when specified group changes

Note: When scaling reports containing images, you should use one of the Resize options when defining the image. (See Images under Selecting Report Elements, p.22) If an image is defined using an Original size option, the image size will remain consistent, but the new dimensions will affect how much of it is displayed.



('Start new page when group changes' option must be set at the group level)

Inserts page breaks when a control break group, which has the Start new page when group changes option set, changes. Page headers and footers will be added to the HTML output where page breaks occur when the output is printed from the browser. Default is to output HTML reports as a single page.

It is important to note that page breaks in HTML may not be supported by all browsers.

ColoursThe Colours tab has options for setting alternating background colours on detail lines:

Select from three Alternate Background Colours options: Default, On, or Off.

Default Alternate background colours are derived from values in two global variables, %RW_BgColour1$ and %RW_BgColour2. The %RW_Bgcolour1$ variable is used for the background colour of the first detail line on each page, or the first detail line in a group, and %RW_Bgcolour2$ is used for the colour of the second detail line.

Colours may be defined using their names (Dark Gray, Black, Dark Red, Light Red, Dark Green, Light Green, Dark Yellow, Light Yellow, Dark Blue, Light Blue, Dark Magenta, Light Magenta, Dark Cyan, Light Cyan, Light Gray, White.), or an RGB setting (RGB:n n n where n=0-255.). If only one colour is set, the other will default to "White". If no colours are set, the system default will be to have no alternating background colour on detail lines.



Custom InterfacesThe Report Writer Designer has two custom interfaces, the Custom Output Destination and the Parameter Interface.

Custom Output Destination. This allows a non-standard output destination using a custom output object to be defined for a report:

Two options are available:

This option merely defines what object to use if custom output is required. The output destination must be set to Custom Output to actually invoke this option. See Setting the Report Destination below.

On Turn on alternating background colours for the current report (overrides system-wide default). Up to two colours must be chosen to alternate as background colours for the detail lines. If one is defined, the other defaults to white. Colour selections may be None, Default and Custom. The Default assumes the Light Gray setting, which uses the current Windows theme background colour. Custom colours can be selected by pressing the palette button, which invokes the Color dialogue.

Off Turn off alternating background colours for the current report. (overrides system-wide default.)

Default Use the default custom object *rpt/useroutput or the object specified in the %RW_UserOutput$ global variable (the latter takes precedence).

Specify Specify the name of the custom object to be used for output for the report (overrides existing default custom output objects). This may be a fixed value or ProvideX expression if the Expression box is checked.



The custom output destination may also be set by selecting Specify Custom Destination from the File menu. For information on creating a custom output object, see Custom Output Object Interface, p.100.

Parameter Interface. This allows the developer to specify a program or panel to be used to process external parameters that are to be used by the report. (See Parameters, p.10.) Three options are available:

For more information on creating a parameter program or panel interface, see Custom Parameter Interfaces, p.104.

If a Parameter Interface is not specified, or if a program or panel is specified and cannot be found, then the generic parameter interface panel supplied with the Report Writer will be used.

Setting the Report Destination

The default destination for a report is the printer. You may set an alternate default destination by setting the Output Definition in the Files menu.

The output destination can be overridden at run-time. This is discussed later under Generating a Report, p.35. To output a report to the specified output destination from within the Report Designer, select Generate Report from the Files menu.

Default Use the generic parameter interface panel supplied with the Report Writer.

Program Specify the program pathname and optional program label (separated with a semi-colon. This may be a fixed value or ProvideX expression if the Expression box is checked; e.g., c:\MyApp\Progs\ParamProg;Init

Panel Specify the panel library and the name of the panel.

Printer and PDF

Send the output to the printer. Optionally, if the Use Internal PDF driver option is set in the System menu (or the ProvideX INI file has an AutoEnablePDF=1 entry in the [Config] section), you can specify a file name with the .pdf extension to output directly into a pdf file.

Clipboard Send tab-delimited output to the Windows clipboard. Cell formatting (font, colour, alignment, borders) is stripped. Output is considered as one page, with one page header and footer.

HTML File Output is an HTML file in tabular format. A style for each cell with data is created to make it easy for an HTML programmer to further customize the output. The generated HTML code is compliant with W3C standards for HTML 4.01 Transitional.

Viewer Output to the ProvideX Viewer to preview the report. From the Viewer, the report can be sent to a printer or to a PDF file.

Custom Output

Send output to a user-created output object. See Custom Output Object Interface, p.100.



Saving the Report DefinitionSave a report definition by selecting Save or SaveAs from the Files menu, or by pressing the Save button on the toolbar. The default extension for a ProvideX report definition is .pvr, although you may specify your own extension. The report definition file is a text-based file comprised of proprietary formatting instructions.

Testing the ReportWhen creating a report definition, you may wish to preview the output. You can output the report to the ProvideX Viewer by selecting Print Preview from the Files menu, or by selecting the Print Preview icon on the toolbar. The preview function will generate the entire report for viewing, so you may wish to apply some filtering logic at the design phase if the report is large and time-consuming. You may also generate the report in any format (printer/pdf, clipboard or HTML) directly from the toolbar, regardless of the defined output destination.

Deleting Report DefinitionsYou can delete report definitions by selecting Delete from the Files menu. This will invoke a dialogue with an input box to enter the name of the report definition file, as well as a browse button to locate and select the file. On Windows-based systems, files can also be deleted from any file selection dialogue.

Report Writer Generating a Report


Generating a Report B MK

Generating a Report

There are several ways to generate the reports created by the ProvideX Report Designer. Reports may be generated from the Designer itself, or generated programmatically using pvxreport object methods. As well, a special ProvideX program can be called from an application or used as a lead program to generate a report. Each approach requires that the input files needed to generate the reports are accessible during the ProvideX session.

Designer Interface, p.35Program CALL, p.35Lead Program, p.35Objects - RunReport( ) Method, p.36

Designer InterfaceThe Report Designer can generate reports directly. Select toolbar icons to generate output to the ProvideX Viewer (Print Preview), the printer or a PDF file, the Windows clipboard, an HTML file, or custom output destination. Alternately, you can send the report to the designated output destination from the Generate Report item in the Files menu. To automatically display HTML and PDF reports using the default browser and PDF reader after they have been generated, set the Auto-Display options for HTML and PDF files in Designer Options, p.43.

Program CALLA report can be generated by calling the *rpt/runreport program using the Run_Call entry point. The first argument in the CALL statement must be the path to the report definition file. A second optional argument can be used to specify a file path or a channel number to print to. A channel number is not needed to output to the clipboard or printer, but is necessary for HTML or PDF output. If no channel number is indicated for printer output, the default printer will be invoked as is. A channel number must be passed as a string.

CALL "*rpt/runreport;Run_Call","c:\rptdef\cust.pvr"CALL "*rpt/runreport;Run_Call","C:\rptdef\cust.pvr",channel$CALL "*rpt/runreport;Run_Call","C:\rptdef\cust.pvr","myrpt.pdf"

Lead ProgramWhen launching ProvideX, the *rpt/runreport program can be run as a lead program to generate a report. The command line requires the path to the report definition file as an argument; e.g.,

C:\pvx\pvxwin32.exe *rpt/runreport -xt=1 -mn -arg c:\rpt\cust.pvr

Topics



A file path may be specified as a second argument to generate output files corresponding to the specified output definition for the report (.prn or .pdf file for printer reports, .htm for HTML output); e.g.,

C:\pvx\pvxwin32.exe *rpt/runreport -arg \rpt\cust.pvr \myrpt.pdf

Objects - RunReport( ) MethodReport generation can also be invoked by accessing objects that define the underlying components of the Report Writer. From ProvideX, pvxreport is the primary object used to generate a report. First, create the object:

rpt=NEW("*rpt/pvxreport")

Once instantiated, the pvxreport object interface provides several methods for generating reports. This includes the RunReport( ) method, which provides three formats for direct control over report generation. However, ultimate program control can be gained using a number of different methods that break the report generation sequence down to individual parts. For a complete list of available methods, refer to the Object-Oriented Interface, p.45.

RunReport(DefinitionFile$)This format of the RunReport( ) method creates the report exactly as defined in the report definition file, which is passed as the only argument. If the printer is the defined output destination, the default printer will be used. Normally, this format cannot be used to generate PDF or HTML files, but it can be used to generate these types of output using custom output object interfaces and by specifying the output file in the 'DestinationFile$ property.

Example:

! Use output destination designated in definition! rpt=NEW("*rpt/pvxreport"); IF rpt=0 \ THEN END rpt'RunReport("MyRptDef.pvr")WrapUp: \ DROP OBJECT rpt END

RunReport(DefinitionFile$,Chan)This format gives the application developer control over the output channel. The application program must open the output channel (which must be compatible with the defined output destination), which is passed to the RunReport( ) method as the second argument. The program must then close the channel after the report is generated. This format cannot be used to generate output to the clipboard.

Note: An overview of Object Oriented Programming in ProvideX can found on the ProvideX website: www.pvx.com.



Example:

! Output to pdf file (Defined output destination is 'printer')! rpt=NEW("*rpt/pvxreport"); IF rpt=0 \ THEN END! Options$="Overwrite;File=MyRpt.pdf;"+rpt'GetPageSetup$("MyRptDef.pvr") OPEN (HFN,OPT=Options$,ERR=WrapUp)"*pdf*"; prt=LFO rpt'RunReport("MyRptDef.pvr",prt) CLOSE (prt)! SYSTEM_HELP "myrpt.pdf"!WrapUp: \ DROP OBJECT rpt END

RunReport( )This format gives the application program control over the report definition and output channel. The program must do all the initial set up: open the output channel, open the report definition, set the output channel, make changes as required (i.e., change input source or output destination), add more filters, and get user parameters (if necessary). After the report is generated, the program must close the report and the output channel.

Example:

! Change the output destination to HTML file ! rpt=NEW("*rpt/pvxreport"); IF rpt=0 \ THEN END! SERIAL "myrpt.htm ",ERR=*NEXT OPEN PURGE (HFN,ERR=WrapUp)"myrpt.htm"; prt=LFO! IF rpt'open("MyRptDef.pvr")=0 \ THEN GOTO WrapUp ! open and init the report definition rpt'OutputHTML(prt) ! set the output channel if rpt'ParamCount()>0 then rpt'AcceptParameters() ! get parameter values from user rpt'RunReport() ! generate the report rpt'close() ! close the report object CLOSE (prt)! SYSTEM_HELP "myrpt.htm "!



WrapUp: \ DROP OBJECT rpt END

For more details on the other methods used in this example, refer to Object-Oriented Interface, p.45.

Other Methods Ultimate program control over report generation may be derived via the methods that conduct each of the steps in the report process:

Besides the required methods, there are many methods and properties that allow an application to alter the report definition; i.e., SetDataSource( ), ScaleToFit SetColumnWidth( ), SetFont( ), SetParameter( ), etc. These must logically be placed after an Open( ) and before a StartReport( ).

Any methods dealing with printer properties must be set, then followed by a SetPrinterProperties( ) method; e.g., SetMargins( ), SetLeftMargin( ), SetRightMargin( ), SetTopMargin( ), SetBottomMargin( ), SetPageOrientation( ). To take effect, these methods must precede the OPEN command used to open the output channel. GetPageSetup$( ) can be used to retrieve the page setup for a report.

Example:

! sortreport - Sort simple reports ! ! This program processes simple reports that have no data groupings, ! and whose column headings are on line three of the page header. ! ! This is a called program that accepts a report definition file ! name as an argument. ! ! After loading the report, the program sets up three parameters ! (SortColumn, StartValue & EndValue) and retrieves these values ! from a user parameter panel interface.

Open(DefinitionFile$) Opens and initializes the report definition.

OutputPrint(chan)OutputClipboard( )OutputHTML(chan)

Sets the appropriate output destination and channel.

StartReport( ) Initializes workspace and objects required by report engine.

ReadData$( ) Retrieves a data record from the input source.

ProcessData( ) Processes the data and output it to the report.

FinishReport( ) Processes summary lines and wrap up report.

Close( ) Resets workspace and releases objects required by the report engine.



! It then sets up a custom sort based on SortColumn and ! sets the background colour of that column to green ! Next it adds filters to process the StartValue and EndValue range ! Lastly, it sets the scale-to-fit option and generates the report ! to the Viewer. ! ENTER ReportName$,ERR=*END ! Rpt=NEW("*rpt/pvxreport") IF Rpt'open(ReportName$)=0 \ THEN GOTO WrapUp ! Check if report has groupings g=Rpt'GetGroup("H","01"); IF g \ THEN EXIT 17 ! ! Add the parameters Rpt'ClearParams() p=Rpt'AddParam() p'Name$="SortColumn" p'Description$="Column to sort by" p'Type$="S" p'Length=60 ! p=Rpt'AddParam() p'Name$="StartValue" p'Description$="Start at" p'Type$="S" p'Length=30 ! p=Rpt'AddParam() p'Name$="EndValue" p'Description$="End at" p'Type$="S" p'Length=30 ! Rpt'SetParameterPanel("ReportParams","app.en") ! ! Get the object identifier for the data source src=Rpt'Source() ! Get column number to sort by and store in SortColumn parameter sts=Rpt'AcceptParameters(); IF sts=0 \ THEN GOTO WrapUp ! Get column info from src using the "SortColumn" parameter SortColumn$=Rpt'GetParameter$("SortColumn") c=src'GetColumnInfo(SortColumn$);



IF c=0 \ THEN c=Rpt'GetCalcField(SortColumn$); IF c=0 \ THEN GOTO WrapUp SortType$=c'Type$,SortVar$=SortColumn$+TBL(SortType$="S","","$") ! Redefine the sort Rpt'ClearSort() ! clear the original sort Rpt'SetSort(-1) ! set to custom sort s=Rpt'AddSortItem() ! add custom sort segment s'SegmentName$=c'Name$ s'Type$=c'Type$ s'Length=c'Length s'Order$="A" s'IgnoreCase=1 ! Find the location of the sort column cell in the detail line

SortColumn$=UCS(SortColumn$),Column=0 line=Rpt'GetGroup("D","L1")'GetLine(1) c=line'CellCount() FOR c cell=line'GetCell(c) IF UCS(STP(cell'Value$,1,"$"))=SortColumn$ \ THEN SortColumn=cell'Column; BREAK NEXT ! Find the cell with the column heading and set the background colour line=Rpt'GetGroup("H","PG")'GetLine(3) c=line'CellCount() FOR c cell=line'GetCell(c) IF cell'Column=SortColumn \ THEN cell'BackgroundColour$="RGB:100,200,100"; BREAK NEXT ! Set up the range filters StartAt$=Rpt'GetParameter$("StartValue") EndAt$=Rpt'GetParameter$("EndValue") IF StartAt$+EndAt$<>"" \ THEN Rpt'ClearFilters(); fs=Rpt'AddFilterSet(); quo$=TBL(SortType$="S","",QUO),FF$=TBL(SortType$="S","",$FF$) IF StartAt$<>"" \ THEN fltr=fs'AddFilter(); fltr'Variable$=SortVar$; fltr'ConditionCode=6; fltr'IsCaseSensitive=0; fltr'SetCompareValue(1,quo$+StartAt$+quo$) IF EndAt$<>"" \



THEN fltr=fs'AddFilter(); fltr'Variable$=SortVar$; fltr'ConditionCode=5; fltr'IsCaseSensitive=0; fltr'SetCompareValue(1,quo$+EndAt$+FF$+quo$) ! ! Turn on the Scale-to-fit option Rpt'ScaleToFit=1 ! Now generate the report Generate_Report: OPEN (HFN,ERR=WrapUp,OPT="Normal;"+Rpt'GetPageSetup$())"*viewer*"; prt=LFO Rpt'OutputPrint(prt) Rpt'RunReport() CLOSE (prt) WrapUp: \ DROP OBJECT Rpt END

There are also methods to retrieve/change data (GetData( ) and SetData$( )) between ReadData$( ) and ProcessData( ) methods. This allows the program to alter the data before it is written.

Example:

! Data modification example! rpt=NEW("*rpt/pvxreport"); IF rpt=0 THEN END IF rpt'open("test.pvr")=0 \ THEN GOTO WrapUp ! Open report definition!OPEN(HFN,OPT="Normal;File=test.prn;"+rpt'GetPageSetup$(),ERR=WrapUp)

"*winprt*"; prt=LFO rpt'OutputPrint(prt) ! Set output channel! IF rpt'ParamCount()>0 \ THEN rpt'AcceptParameters() ! Could also use SetParameter method! IF rpt'startreport()=0 \ THEN GOTO WrapUp ! Set up workspace! r$=rpt'ReadData$() ! Get a data record WHILE r$<>"" LET Balance=rpt'GetData("Balance") ! Get value of Balance rpt'SetData$("Balance",Balance*100) ! Modify Balance rpt'processdata() ! Process/output data r$=rpt'ReadData$() ! Get a data record WEND



! rpt'finishreport() ! Wrap up report rpt'close() ! Reset workspace WrapUp: \ DROP OBJECT rpt CLOSE(prt,ERR=*NEXT) END

Another way to change data is to alter the record information returned by the ReadData$ method, then pass the altered record back to the Report Writer as an argument to the ProcessData method.

Example: ! GOSUB Check_Access ! Sets NoAccess flag to 0/1 ! SourceIolist$=rpt'SourceIolist$() ! Get iolist for input source object ! r$=rpt'ReadData$() WHILE r$<>"" ! if the user is not to have access to restricted data ! ! Load the record into the record fields ! ! Set restricted fields to 0 ! ! Reload the record IF NoAccess \ THEN READ DATA FROM r$ TO IOL=SourceIolist$; CreditRating=0,Balance=0; r$=REC(SourceIolist$) rpt'ProcessData(r$) ! Pass the altered record back for processing r$=rpt'ReadData$() WEND ! For the complete list of methods refer to the Object-Oriented Interface, p.45.

Report Writer Designer Options


Designer Options B MK

D es igner Options

Designer Options allow you to set options and preferences that govern the Report Designer environment. To set these options, select Designer Options from the Options menu.

Auto-Display Automatically display HTML and PDF reports using the default browser and PDF reader when reports are generated in those formats from the Report Designer.

Default Column Width

Set the column width (in inches or cm) for new reports and new columns. Default is a half inch or 1 cm depending on the Metric Display setting.

Default Row Height

Set the default line height (in inches or cm) for new reports and new lines. An Auto setting will determine the default line height based on the size of the default font. (Default is Auto.)

Font Specify the default font, font size and font style to use for new reports. The font name may be selected from the list, or entered in the input box above the list. This allows you to select a font that is not resident on the system.

Numeric Format Specify the default numeric format mask to use for group functions. (This can also be set in the Group Functions interface. See Group Functions, p.20)

Report Writer Designer Options


Testing Parameters

Test mode restricts the number of records processed when a report is generated. (A processed record is one that is included in the report; i.e. it has not been rejected by the filtering process.) Specify the number records to be processed when in test mode. Turn test mode on and off by clicking the Use test mode option here or on the main Designer panel below the report layout.

Units of Measure Display the Designer layout using metric (centimeter) units. (There will be a difference in the size of the display when switching to and from metric display.)

Save Settings Save the current options for future sessions when the Designer is closed.

Report Writer Object-Oriented Interface


Object-Oriented Interface B MK

Object-Or iented Interface

The ProvideX Report Writer includes an object-oriented interface that gives developers control over a report at virtually every stage, from definition to report generation. Available Report Writer objects and subordinate objects listed below.

pvxreport

The pvxreport object embodies the report definition, which consists of a series of subordinate objects for filter processing, sort sequence, parameters, groups, lines, and cells. Methods are available to create, update and delete these objects. The pvxreport object also has methods to generate the report – discussed in detail under Generating a Report, p.35. Use the ProvideX NEW( ) function to create the pvxreport object:

ObjectIdentifier=NEW("*rpt/pvxreport")

Sub-objects are created and maintained by pvxreport methods. Many of these methods are used by the pvxreport object itself to store the report definition and generate the report.

pvxreport Properties and Methods:

Topics pvxreportrptgrouprptline

rptcellrptcalcfieldrptgroupfunc

rptsortrptparamrptfilterset

rptfilterrptdesigner

pvxreport ObjectProperties Descriptions

BookMarkPDF Indicates whether bookmarks are to be generated in PDF output. 1=On, 0=Off (Default is 0)

Designer Object identifier for the rptdesigner object which stores and saves Report Designer options and preferences.

LastUpdate$ Date/time stamp (DTE(0:"%Ys/%Mz/%Dz %Hz:%mz")) and user ID associated with the last change to the report definition.

PaginateHTML Indicates whether page breaks are to be inserted into HTML output when a group changes (rptgroup NewPage property must be set to 1). 1=On, 0=Off (Default is 0. HTML is output as a single page.)

ReportFile$ The report definition file.



ReportName$ The assigned name of the report.

ScaleToFit Boolean property indicating if the report is to be scaled to fit. 1=On, 0=Off (Default is 0.

SuppressEmpty Indicates that output to reports that have no data available is to be suppressed. 1=On, 0=Off (Default is 0. Reports with no data will be printed with a page header, summary and page footer, if defined)

UserLogic Name of user logic object. For more information, see Report Writer User Interfaces, p.95.

pvxreport ObjectMethods Descriptions

AcceptParameters( ) Display the interactive interface to accept parameter values from the user. Returns 1.

AddAlternateCell(ObjID) Add an AlternateCell rptcell object to the main rptcell object specified in ObjID. Returns AlternateCell.

AddCalcField( ) Creates a new rptcalcfield object using the next available sequence number. One object is created for each calculated field.

The sequence number can be used as the index number to identify the object when using the RemoveCalcField( ) and GetCalcField( ) methods.

CalcFieldCount is incremented. Returns the object identifier if successful, 0 if not

AddCell(GrpIdx,LnIdx) Creates a new rptcell object using the next available sequence number. Only cells with data or formatting need to have an rptcell object created for them.Grpidx - Sequence number of the section where the cell is located.Linidx - Sequence number of the line where the cell is located.CellCount for the specified line is incremented. Returns the object identifier if successful, 0 if not.

pvxreport ObjectProperties Descriptions



AddFilter(ObjID,SetIdx )

AddFilter(SetIdx)

AddFilter( )

Creates a new rptfilter object within the rptfilterset object specified by SetIdx in the given ObjID object, using the next available sequence number. If no arguments are specified, the rptfilter object is created in the first rptfilterset object of the current object.

One object is created for each filter definition. The sequence number can be used as the index number to identify the object when using RemoveFilter( ) and GetFilter( ) methods.

If SetIdx is not specified, a rptfilter object will be added to the first rptfilterset object.

FilterCount for the RptFilterSet is incremented. Returns the object identifier if successful, 0 if not.

AddFilterSet(ObjID)

AddFilterSet( )

Creates a new RptFilterSet object in the specified object ObjID, (or current object if omitted) using the next available sequence number. One object is created for each filter set. The sequence number can be used as the index number to identify the object when using the RemoveFilterSet( ) and GetFilterSet( ) methods.

FilterSetCount is incremented. Returns the object identifier if successful, 0 if not

AddGroup( ) Creates a new rptgroup object using the next available sequence number. Group sequence is very important as the sections must be added in a very specific sequence: Page header, [Group 01 header],[Group 01 header], [Group nn header], Detail Line, [Detail Line nn] [Group nn footer], [Group 02 footer], [Group 01 footer], Report Summary, Page Footer.

One group is created for each report section.

The sequence number can be used as the index number to identify the object when using the RemoveGroup( ) and GetGroup( ) methods.

BreakCount is incremented. Returns the object identifier if successful, 0 if not.




AddGroupFunction( ) Creates a new rptgroupfunc object using the next available sequence number. One object is created for each function definition.

The sequence number can be used as the index number to identify the object when using the RemoveGroupFunction( ) and GetGroupFunction( ) methods.

FunctionCount is incremented. Returns the object identifier if successful, 0 if not.

AddLine(GrpIdx) Creates a new rptline object using the next available sequence number. It is important to add the lines in the correct sequence, as this is the sequence in which the lines will be displayed in the report.

GrpIdx - Sequence number of the section where the report line belongs.

One object is created per line.

LineCount relative to the specified section is incremented. Returns the object identifier if successful, 0 if not.

AddParam( ) Creates a new rptparam object using the next available sequence number. One object is created for each parameter.

The sequence number can be used as the index number to identify the object when using the RemoveParam( ) and GetParam( ) methods.

ParamCount is incremented. Returns the object identifier if successful, 0 if not.

AddSortItem( ) Creates a new rptsort object using the next available sequence number. These objects are added in sequence, one for each segment.

The sequence number can be used as the index number to identify the object when using the RemoveSortItem( ) and GetSortItem( ) methods.

SortItemCount is incremented. Returns the object identifier if successful, 0 if not.




BreakCount( ) Returns the number of sections in the report. This includes the Page header, Detail Lines, Report Summary, Page footer, as well as the headers and footers for all control break group definitions.

CellCount(GrpIdx,LnIdx) Returns the number of data-bearing cells in a line.

GrpIdx - Sequence number of the section where the cell is located.LnIdx - Sequence number of the line where the cell is located.

Returns 0 if the arguments are invalid.

Note: A cell contains data or formatting. Empty cells do not have an assigned object.

CalcFieldCount( ) Returns the number of defined calculated fields.

CheckFilters(Fset,R$,K$,C$) Evaluates the conditions in a rptfilterset object based on record and key data.Fset - Object identifier for the rptfilterset to be evaluated. R$ - Record data.K$ - Key data.C$ - Calculated field data.

R$, K$, and C$ are in record format. If not specified, the current data, key and calculated field values will be used. Returns 1 (true) or 0 (false).

ClearCalcFields( ) Removes all rptcalcfield objects. Returns 1.

ClearFilters (ObjID)

ClearFilters( )

Removes all rptfilterset objects from the specified object, or current object if ObjID is not specified.

Returns 1.

ClearGroupFunctions( ) Removes all rptgroupfunc objects. Returns 1.

Note: The result of any function used in an expression in the report will be zero.

ClearGroups( ) Removes all sections in the report (basically clears all sections, lines and cells). Returns 1.

ClearParams( ) Removes all rptparam objects. Returns 1.




ClearSort( ) Removes all rptsort objects. Returns 1.

Note: If used, SetSort( ) or AddSortItem( ) is used to create a new sort order.

Close( ) Reset workspace and sub-objects. Return 1.

DataSource$( ) Returns the name of the current source. Depending on the source type, this could be the logical table name, the simple path, a view name or the source name for a custom data source object.

EvaluateCalcFields$( ) Evaluates the calculated fields and returns the values in record format, based on the IOLIST returned by GetCalcFieldIolist$( ).

FilterCount(ObjID,SetIdx)

FilterCount(SetIdx)

FilterCount( )

Returns the number of rptfilter objects in the rptfilterset object specified by SetIdx, in the given ObjID (or current object if not specified.) If no arguments are specified, returns the number of rptfilter objects in the first rptfilterset object of the current object.

FilterSetCount(ObjID)

FilterSetCount( )

Returns the number of rptfilterset objects in the given ObjID object, or current object if not specified.

FinishReport( ) Wraps up the report. Returns 1 when a report is generated.

GetBackgroundColor$(n)

GetBackgroundColour$(n)

Returns background colour 1 or 2, depending on n.

GetBackgroundColorOption$( )GetBackgroundColourOption$( )

Returns the background colour option. See SetBackgroundColourOption$( )

FunctionCount( ) Returns the number of defined group functions.

GetBottomMargin( ) Returns the size of the bottom margin in 1000’s of an inch. Printer default is indicated as -1.




GetCalcField(idx |name$ ) Returns the identifier for a rptcalcfield object.

idx - Sequence number of the object.

name$ - Name of the calculated field.

This allows access to all rptcalcfield properties and methods. Returns 0 if the sequence number is invalid.

GetCalcFieldEvaluationString$( )

Returns a ProvideX expression comprised of the assignment pairs used to evaluate the calculated fields.

GetCalcFieldIolist$( ) Returns a compiled IOLIST consisting of the calculated fields.

GetCalcFieldList$([sep$[,flag$]]

Returns a list of calculated field names.

Sep$ - Separator to use after each name. (optional) If null or omitted, the default is a comma.Flag$ - Set to "D" to include the desciption in parentheses with each field name. (optional)

GetCell(GrpIdx,LnIdx,CellIdx) Returns the identifier for a rptcell object.

GrpIdx - Sequence number of the section where the cell is located.LnIdx - Sequence number of the line where the cell is located.CellIdx - Sequence number of the rptcell object.

This allows access to all rptcell properties. Returns 0 if the arguments are invalid.

GetColumnCount( ) Returns the number of columns in the report.

Note: This cycles through all the groups, lines, and cells to determine the highest column number – so save off this value if you need to use it more than once, rather than calling this method repeatedly.




GetColumnLocation(Column) Returns the location of the start of a column relative to the left most margin. The first column is at location 0.

Column -Number of the column whose location is to be returned.

Units are points (72’s of an inch).

GetColumnWidth(Column) Returns width of the specified column in points (72’s of an inch).

GetCondition$

(ObjID, SetIdx,FilterIdx)

GetCondition$

(SetIdx,FilterIdx)

GetCondition$(FilterIdx)

Returns a string containing the ProvideX expression associated with a filter.

ObjID - Object identifier for object containing the rptfilterset objects. Current object, if omitted.SetIdx - Index of the RptFilterSet object. If omitted, default is first filter set in the current object.FilterIdx - Index of the RptFilter object.

Returns null if the sequence number is invalid.

GetCondition$(ObjID) Returns a ProvideX expression encompassing all conditions in all filtersets in the given ObjID object. For example, if an object has two filter sets, one which has two filters, TYPE$="M" and BALANCE>1000, and the other also has two filters, TYPE$="P" and BALANCE>10000, then this method will combine these and return ((TYPE$="M" AND BALANCE>1000) OR (TYPE$="P" AND BALANCE>10000)).

GetConditionDescription$(ObjID)

Returns a prose description of conditions; e.g., "CustomerBalance is less than 0."

ObjID - Object ID for a *rpt/rptfilterctl object.

(The description does not indicate case sensitivity of the condition.)




GetData$(VarName$) Returns the string data contained in a variable used in a report.

VarName$ - Name of the variable whose value is to be returned; e.g.,MyVar$=x’GetData$("MyVar$")

Returns 0 if not successful.

GetDestination$( ) Returns the output destination (i.e., the file to be opened, such as *winprt*, *viewer*, *pdf*, or *.htm files, etc.) of currently-set output device.

GetDestinationFile$( ) Returns the file to be specified in the FILE= clause of the open option for *winprt* or *pdf*.

GetDestinationOption$( ) Returns the output destination option (e.g., Normal, Default, Asis) of the currently set output device.

GetFilter

(ObjID,SetIdx,FilterIdx)

GetFilter(SetIdx, FilterIdx)

GetFilter(FilterIdx)

Returns the identifier for a rptfilter object.

ObjID - Object identifier for object containing rptfilterset objects. Current object, if omitted.SetIdx - Index indicating which RptFilterSet object. If omitted, default is first filter set.FilterIdx - Index of the RptFilter object

This allows access to all rptfilter properties and methods. Returns 0 if sequence number is invalid.

GetFilterSet

(ObjID, SetIdx)

GetFilterSet (SetIdx)

Returns the identifier for a RptFilterSet object.

ObjID - Object identifier for object containing rptfilterset objects. Current object, if omitted.SetIdx -- Index indicating which RptFilterSet object.This allows access to all RptFilterSet properties and methods. Returns 0 if not successful.

GetFont$( ) Returns a comma-separated string denoting the default font name, its point size, and optionally, its attributes: I (italics), B (bold).




GetGroup(idx) Returns the identifier for a rptgroup object.


This allows access to all rptgroup properties and methods.

Returns 0 if the sequence number is invalid.

GetGroup(Type$,Level$) Returns the identifier for a rptgroup object.

Type$ - Section type code: H=header, F=footer, D=detail line

Level$ - Two-letter level code: PG = pageLn = detail line00 = report summarynn = control break group level (e.g. 01)RP = report level

Returns 0 if any arguments are invalid.

GetGroupFunction(idx) Returns the identifier for a rptgroupfunc object.


This allows access to all rptgroupfunc properties and methods. Returns 0 if the sequence number is invalid.

GetIolist$(GrpIdx,LnIdx) Returns the compiled IOList for a report line.

Grpidx - Sequence number of the report section.Lnidx - Sequence number of the line in the specified section.

Returns null if either argument is invalid.

GetLeftMargin( ) Returns the size of the left margin in 1000’s of an inch. Printer default is indicated as -1.

GetLine(GrpIdx,LnIdx) Returns the identifier for a rptline object.

Grpidx - Sequence number of the report section.Lnidx - Sequence number of the line in the specified section.

This allows access to all rptline properties and methods. Returns 0 if the arguments are invalid.




GetMargins$( ) Returns a colon-separated string consisting of the size of the left:top:right:bottom margins. Units are in 1000’s of an inch. Printer default is indicated as -1.

GetOutputChannel( ) Returns the channel number to the output device.

GetOutputDevice$( ) Returns a code representing the current output device: P (printer), C (clipboard), H (HTML), V (ProvideX Viewer), U (custom output object).

GetPageOrientation$( ) Returns orientation setting: P (portrait), L (landscape).

GetPageSetup$( )

GetPageSetup$(RptDef$)

Retrieve the printer setup string containing margin and orientation settings to be used with an OPEN directive to an output device (*winprt*, *pdf*, *viewer*). When used, must include printer option string (i.e., Normal; Asis; etc.) prepended to it.

RptDef$ - Name of the report definition file from which to get the setup string. If no file name is given, returns the setup string of the currently open report.

OPEN(1,ERR=*END)"*winprt*;OPT="Normal;File=test.prn;"+rpt'GetPageSetup$("myreport.pvr")

GetPaperSize( ) Returns the currently selected form number. (Default is 0.)

GetParam(idx) Returns the identifier for a rptparam object.


This allows access to all rptparam properties and methods. Returns 0 if the sequence number is invalid.

GetParameter$(ParmName$) Returns the string value of a parameter.

ParmName$ - Name of parameter (not case sensitive) whose value is to be returned. The name should not end with $.

Returns null if a parameter with the specified name does not exist.




GetParameter(ParmName$) Returns the numeric value of a parameter.

ParmName$ - Name of parameter (not case sensitive) whose value is to be returned.

Returns 0 if ParmName$ is invalid.

GetParameterLibrary$( ) Returns the name of the library where the parameter interface panel is located.

GetParameterPanel$( ) Returns the name of the panel to be used in the user parameter interface.

GetParameterProgram$( ) Returns the program path and optional program label (separated by a semi-colon) to be used as the user parameter interface, or an expression (prefixed by an equal sign (=)) that can be evaluated to determine the program name and optional label.

GetParamList$( )

GetParamList$([Sep$])

Returns a list of parameter names.

Sep$ - Item separator (if omitted, default separator is a comma.

GetRightMargin( ) Returns the size of the right margin in 1000’s of an inch. Printer default is indicated as -1.

GetSortDescription$( ) Returns a “+”-separated string consisting of the columns that make up the sort sequence.

Returns null if unsuccessful.

GetSortItem(idx) Returns the identifier for a rptsort object.


This allows access to all rptsort properties and methods. Returns 0 if sequence number is invalid.

GetSortKey( ) Returns the key number of a pre-defined key, or -1 for a custom key.

GetSourceType$( ) Returns a code representing the source type:

P ProvideX file with an embedded dictionary, identified by the path name.

L ProvideX file with an embedded dictionary, identified by the table name.

V ProvideX View.

O Custom data source object.




GetSystemVariable$(idx) Returns the specified system variable name.

GetSystemVariableCount( )

Returns the total number of standard system and user-defined system variables.

GetSystemVariableDescription$(idx)

Returns the specified system variable description..

GetSystemVariableDescriptions$( )

GetSystemVariableDescriptions$(Sep$)

Returns a string of Sep$-separated descriptions. Default Sep$=SEP

GetSystemVariableLength(idx)

Returns the maximum length of the value stored in the specified variable.

GetSystemVariables$( )

GetSystemVariables$(Sep$)

Returns a string of Sep$-separated descriptions. Default Sep$=SEP

GetTopMargin( ) Returns the size of the top margin in 1000’s of an inch. Printer default is indicated as -1.

GetUserOutputObject$(Level$)

Returns the user output object for the indicated Level$:D - Returns the name of the default user output object.R - Returns either the name of the user output object specified for the current report, or an expression (prefixed by an equal sign (=) that can be evaluated to determine the name of the user output object specified for the current report.




GroupCount( ) Returns the number of sections in the report. This includes the Page header, Detail Lines, Report Summary, Page footer, as well as the headers and footers for all control break group definitions.

Same as BreakCount( ).

IsOutputNoChannel( ) Returns a boolean value (0/1) indicating whether the output is not to be sent to an output channel, such as output to the clipboard.

IsOutputNoPaging( ) Returns a boolean value (0/1) indicating whether the report is to be printed without page breaks.

IsOutputPrinterCompatible( )

Boolean value indicating whether or not the output is printer compatible, and if page properties (such as orientation and margins) are to be set up when the output device is opened. This is applicable for output to *winprt*, *pdf*, and *viewer*. This should be set to zero for html or clipboard output, for example.

LineCount(GrpIdx) Returns the number of lines in a section. Returns 0 if the argument is invalid.

Grpidx - Sequence number of the report section.

Open(RptDefFile$) Open and initialize the report. Returns the identifier for the data source object if successful.

RptDefFile$ - Name of the report definition file.

This method opens the data source and creates the sub-objects used by the Report Writer and loads them with the information contained in the definition file.

If an error occurs during the execution of this method, the error will invoke the ERR= branch in the method call, so be sure to include this as part of the application program logic; e.g.,

sts=rpt'Open(RptDef$,err=RptErr)

OutputClipboard( ) Sets the output device to be the Windows clipboard, and sets the output channel to 0. Returns 1.




OutputDevice(DeviceCode$,channel)

Generic method to set the output device and channel. The output device is identified by a device code:

C - Clipboard H - HTML output P - Printer V - ProvideX Report Viewer U - Custom user output object

OutputHTML(chan) Sets the output device to HTML, and sets the output channel. Returns 1.

chan - Output channel number to a .htm file.

OutputPrint(chan) Sets the output device to be a printer, and sets the output channel. Returns 1.

chan - Output channel number to the printer device (*winprt* or *pdf*).

Note: If using this method to generate a pdf file, the channel should be opened, using the *pdf * device with the FILE= option:

Open(chan)"*pdf*;File=FileName"

OutputUser([channel]) Sets the output device to be a custom user output object, and sets the output channel.

OutputViewer(channel) Sets the output device to be the ProvideX Report Viewer, and sets the output channel.

ParamCount( ) Returns the number of defined parameters.

ProcessData( ) Processes the current data record. Processing includes dealing with control breaks, group function calculations, and outputting the data. Returns 1.

ProcessData(Record$) Processes the data using the data in a record.

Record$ Data record

Processing includes dealing with control breaks, group function calculations, and outputting the data. Returns 1.




ReadData$( ) Reads a record from the data source. Returns the record, or null at End-of-file.

RemoveAlternateCell

(ObjID)

Drop the AlternateCell rptcell object from the main rptcell object specified in ObjID and set AlternateCell to zero.

RemoveCalcField(idx) Removes a rptcalcfield object.

idx - Sequence number of object to be removed.

If a rptcalcfield object is removed, the sequence numbers of the rptcalcfield objects with higher sequence numbers are adjusted down. CalcFieldCount is decremented. Returns the object identifier if successful, 0 if not.

RemoveCell

(GrpIdx,LnIdx,CellIdx)

Removes a rptcell object.

Grpidx - Sequence number of the section in which the cell is located.

Lnidx - Sequence number of the line in which the cell is located.

Cellidx - Sequence number of the cell to be removed.

If a rptcell object is removed, the sequence number of the rptcell objects with higher sequence numbers are adjusted down.

CellCount is decremented for the line. Returns the object identifier if successful, 0 if not.

RemoveFilter(ObjID, SetIdx,FilterIdx)RemoveFilter(SetIdx, FilterIdx)RemoveFilter (FilterIdx)

Removes a rptfilter object.ObjID - Object identifier for the object containing the rptfilterset object. Current object, if omitted.SetIdx - Index indicating which rptfilterset object. If not specified, defaults to the first rptfilterset object in the current object.FilterIdx - Sequence number of the rptfilter object to be removed.If a rptfilter object is removed, the sequence numbers of the rptfilter objects with higher sequence numbers are adjusted down.FilterCount is decremented. Returns the object identifier if successful, 0 if not.




RemoveFilterSet (ObjID, SetIdx)RemoveFilterSet (SetIdx)

Removes a rptfilterset object.ObjID - Object identifier for the object containing the rptfilterset object. Current object, if omitted.SetIdx - Sequence number of the object to be removed.If a RptFilterSet object is removed, the sequence number of the RptFilterSet objects with higher sequence numbers are adjusted down.FilterSetCount is decremented.Returns the object identifier if successful, 0 if not.

RemoveGroup(idx) Removes a rptgroup object.idx - Sequence number of object to be removed.If a rptgroup object is removed, the sequence number of the rptgroup objects with higher sequence numbers are adjusted down. This removes all lines and cells associated with the section.BreakCount is decremented. Returns the object identifier if successful, 0 if not.Note: If a control break group is to be removed, remove both the header and footer sections.

RemoveGroupFunction(idx) Removes a rptgroupfunc object.idx - Sequence number of object to be removed.If a rptgroupfunc object is removed, the sequence number of the rptgroupfunc objects with higher sequence numbers are adjusted down.FunctionCount is decremented. Returns the object identifier if successful, 0 if not.




RemoveLine(GrpIdx,LnIdx) Removes a rptline object and all cells associated with the line.

Grpidx - Sequence number of the section in which the line is located.

Lnidx - Sequence number of the line to be removed.

If a rptline object is removed, the sequence number of the rptline objects with higher sequence numbers are adjusted down.

LineCount is decremented for the section. Returns the object identifier if successful, 0 if not.

RemoveParam(idx) Removes a rptparam object.


If a rptparam object is removed, the sequence numbers of the rptparam objects with higher sequence numbers are adjusted down.

ParamCount is decremented. Returns the object identifier if successful, 0 if not.

RemoveSortItem(idx) Removes a rptsort object.


If a rptsort object is removed, the sequence numbers of the rptsort objects with higher sequence numbers are adjusted down.

SortItemCount is decremented. Returns the object identifier if successful, 0 if not.

ResetPrinterProperties( ) Resets the original printer properties. Must be preceded by the SetPrinterProperties( ) method.




RunReport( ) Generates a report.

This format gives the application program control over the report definition and output channel. The program must do all the initial setup: open the output channel, open the report definition, impose any desired changes to the definition, and get user parameters (if necessary). After the report is generated, the program must close the report and the output channel.

For more details, see Objects - RunReport( ) Method, p.36.

RunReport(RptDefFile$) Generate a report using default settings. Returns 1 if successful, 0 if not.

RptDefFile$ Name of the report definition file.

Note: Cannot be used to generate HTML or pdf files.


RunReport(RptDefFile$,Chan) Generate a report; output to channel.

RptDefFile$ Name of the report definition file.

Chan Channel to output the report to.

The application program must first open the channel to the output device, which must be compatible with the defined output destination, and pass the channel as an argument. When the RunReport ( ) method is complete, the application program must then close the channel.


Save(RptDefFile$) Save the report definition currently stored in the pvxreport object and its subordinate objects.

RptDefFile$ Name of the file to save the report definition to.

The standard extension for report file definitions is .pvr, but this is not necessary. Returns 1.




SetBackgroundColor

(Clr1$ [,Clr2$])

SetBackgroundColour

(Clr1$ [,Clr2$])

Set up to two colours for alternating background colours on detail lines (if one colour is set, the second colour defaults to white). Use colour names ("White", "Dark Gray", "Light Red", etc.) or RGB settings; e.g., RGB:255,0,128.

SetBackgroundColorOption(Opt$)

SetBackgroundColourOption(Opt$)

Set the background colour option:

0=Off. Report does not use alternating background colours1=On. Report uses alternating background colours set using SetBackgroundColour( ) method.2=Default. Use of alternating background colours based on setting %RW_BgColour1$ and %RW_BgColour2$ variables.

SetBottomMargin(MargSize) Sets the size of the bottom margin. Returns 1.

MargSize - Size of the margin in 1000’s of an inch, or -1 to set printer default.

See SetPrinterProperties( ).

SetColumnWidth(Col,Width) Sets the width of a column. Returns 1.

Col - Number of column whose width is to be adjusted.

Width - Width of the column, in points (72’s of an inch).

SetData$(VarName$,Val$) Assigns a string value to a variable used in the report.

VarName$ - Name of the variable to which to a value will be assigned.

Val$ - String value to assign to the VarName$ variable.

For example,

CurrentRecord$=x’SetData$("MyVar$","abc")

returns the current record with the updated value.




SetData$(VarName$,Val) Assigns a numeric value to a variable used in the report.

VarName$ - Name of the variable to which to a value will be assigned.

Val - Numeric value to assign to the VarName$ variable.

For example,

CurrentRecord$=x’SetData$(“MyVar”,12)

Returns the current record with the updated value.

SetDataSource(ds$,st$[,fo$]) Sets the data source to be used by the report. Arguments include:

ds$ - Table name, file path, view name or data source name for a custom data source object

st$ - Source type: L (table name), P (file path), V (view name), O (custom data source object).

fo$ - File object name (i.e., name of the custom data source object). For source type O only.

Returns the object identifier if successful, 0 if not.

SetFont(Font$) Sets the default font for the report. Returns 1.

Font$ - Comma-separated string consisting of the font name and optionally, the negative point size and the style (B (bold) and/or I (italic)); e.g., SetFont("Arial,-12,BI").

SetHyperlink

(GroupIdx,LineIdx,CellIdx,

Hyperlink$,Xflg$,Option$)

SetHyperlink

(CellObjID,Hyper-

link$,Xflg$,Option$)

Puts an HTML hyperlink in the specified cell. (The associated text to be displayed on the report must be specified by setting the cell's Format$ and Value$ properties independently.)

Where:

Hyperlink$ - Hyperlink address (may be fixed literal or expression)

Xflg$ - X, F or blank (default). "X" indicates that Hyperlink$ is an expression.

Option$ - Display option:

0=Use current browser window (default) 1=Use new browser window




SetImage

(GroupIdx,LineIdx,Cel-

lIdx,ImagePath$,Xflg$,Dis-

pOpt$)

SetImage

(CellObjID,Image-

Path$,Xflg$,DispOpt$)

Puts an image in the specified cell. (Alternate text may be specified by setting the cell's Format$ and Value$ properties independently.)

Where:

ImagePath$ - Path to the image (may be fixed or expression).

Xflg$ - X, F or blank (default). "X" indicates that ImagePath$ is an expression.

DispOpt$ - Display Option:

1 = Original size, align top left.2 = Original size, centre in region.3 = Resize to fit region.4 = Resize with same aspect ration, align top left.5 = Resize with same aspect ration, centre in region

SetLeftMargin(MargSize) Sets the size of the left margin. Returns 1.

MargSize - Size of the margin in 1000’s of an inch, or -1 to set printer default.


SetMargins(Left,Top,Right,Bot) Sets all printer margins. Returns 1.

Left - Left margin size.Top - Top margin size.Right - Right margin size.Bot - Right margin size.Margin sizes are in 1000’s of an inch. Printer default is indicated using -1. If a value is negative, then the default -1 is set.


SetOutputDevice(DevCode$) Sets the device to handle output.DevCode$ - Single letter code to indicate the output device: P (printer), C (clipboard), H (HTML file), V (ProvideX Viewer), U (custom output object)If code is invalid, the device is set to P. Returns 1 if successful, 0 if not.




SetPageOrientation(OrCode$) Sets printer orientation.OrCode$ - Valid arguments are P (portrait) or L (landscape).Returns 1 if the argument is valid, 0 if not.


SetParameter(Parm$,Val$)SetParameter(Parm$,Val)SetParameter(idx,Val$)SetParameter(idx,Val)

Sets the string value of a parameter.Parm$ - Name of parameter (not case sensitive) to be set.Idx - Sequence number of the parameter to be set.Val$ - Parameter value to be assigned. May be used for string or numeric parameter values.Val - Numeric parameter value to be assigned.Returns 1 if successful, 0 if the named parameter does not exist or if value is outside defined range.

SetPaperSize(FormNumber)

Sets the form number to use when opening a printer device. If the FormNumber is non-zero, then the PAPERSIZE=FormNumber clause will be used when opening the printer.

SetParameterPanel([Panel$,Lib$])

Set the name of the panel and panel library to be used in the user parameter interface. If set, the parameter program will be set to null.

SetParameterPanel() , with no arguments, resets the parameter panel to null.




SetParameterProgram(Prog$ [,Xflg$])

Set the path of the program to be used in the user parameter interface. If set, the parameter panel and library will be set to null.

Prog$ - Contains the pathname of the program or an expression that will be evaluated to get the pathname.

Xflg$ - "F" or "X" to indicate whether Prog$ contains a fixed value (F) or an expression (X); e.g., SetParameterProgram("%ParamProgR","X"), SetParameterProgram("ParamProg")

SetParameterProgram( ) with no arguments resets the parameter program to null.

SetPrinterProperties( ) Sets defined printer properties. The SetMargins( ), SetLeftMargin( ), SetRightMargin( ), SetTopMargin( ), SetBottomMargin( ), and SetPageOrientation( ) must be followed by a SetPrinterProperties( ) method in order to be set. All must precede an OPEN to take effect.

SetPrinterProperties( ) also saves off the original printer defaults so they can be restored using the ResetPrinterProperties( ) method. Returns 1.

SetRightMargin(MargSize) Sets the size of the right margin. Returns 1.MargSize - Size of the margin in 1000’s of an inch, or -1 to set printer default. See SetPrinterProperties( ).

SetScale(ScalingFactor$) For internal use only. Sets the scaling factor. Scaling factor is a computed fractional number greater than 0. A factor between 0 and 1 would decrease the size of the output, and a factor greater than 1 would increase the size. The scaling factor is set internally in the StartReport( ) method.

SetSort(KeyName$) Sets pre-defined sort sequence. Returns 1 if successful, 0 if not. KeyName$ - Name of key to be used as sort sequence.




rptgroupThe rptgroup object is a data member of the pvxreport object interface, delegated to store and manipulate a group or section definition. One object is created for each report section. The order in which various rptgroup objects are created is important, as the sections must be added in a very specific sequence: Page header, [Group 01 header],[Group 01 header], [Group nn header…], Detail Line, [Detail Line nn], […Group nn footer], [Group 02 footer], [Group 01 footer], Report Summary, Page Footer. The pvxreport GetGroup( ) method can be used to retrieve the object identifier for a rptgroup object, which allows access to all the object's methods and properties.

SetSort(KeyNumber) Sets pre-defined sort sequence. Returns 1 if valid, 0 if not.KeyNumber - Set to -1 for a custom sort. For a pre-defined sort, set to the number of the key to be used as the sort sequence. (Base 0 for primary key).

SetTopMargin(MargSize) Sets the size of the top margin. Returns 1.MargSize - Size of the margin in 1000’s of an inch, or -1 to set printer default. See SetPrinterProperties( ).

SetUserOutputObject$

(Lvl$,ObjNm$ [,Xflg$])

Set the name of the user output object for the specified level. Lvl$ - Level at which to apply the output object:

D - Default levelR - Report level

ObjNm$ - Contains the name of the object or an expression that will be evaluated to get the object name.

Xflg$ - "F" or "X" to indicate whether ObjName$ contains a fixed value (F) or

SortItemCount( ) Returns the number of segments in the sort sequence.

Source() Returns the identifier for the data source object.

SourceIolist$() Returns the data source IOList in compiled format.

SourceKeyIolist$() Returns the key IOList in compiled format for data sources with external keys.

StartReport( ) Initialize the workspace required to generated the report. Returns 1.




The rptgroup object has its own subordinate object, the rptline object, which in turn has its own subordinate object, the rptcell object. These are used to define the report lines and data cells in a report section. The rptfilterset object defines conditions associated with conditional detail line groups. The rptgroup object has methods to create and access all these objects.

rptGroup Properties and Methods

rptGroup ObjectProperties Descriptions

BlankPageToFollow Follow the Report Header with a blank page (for duplex printing). Report Header only.

CenterContents Centre contents in the page. Report Header/Trailer only.

CountPage Include the Header page(s) in the page count. Report Header only.

FillToBottom Boolean value (0/1) to indicate if the filler line is to be used to fill the space between the current section and the page footer (or page bottom) when the current section is the last section to be output to a page.

IncludePageFooter Output the page footer with the Report Header or Trailer. Report Header/Trailer only.

IncludePageHeader Output the page header with the Report Header or Trailer. Report Header/Trailer only.

Level$ Two-character code indicating the section level: PG (page level), L1(detail line), 00 (report summary level), 01 – 16 (control break levels).

When PG and L1 levels are set, the Name$ property is set to null, and the NewPage and RepeatHeader properties are set to 0. When the 00 and RP levels are set, the Name$ property is set to null. Level$ is set to null if the code is invalid.

Name$ Name of the sort element on which a control break group is based following rules of element names; i.e., starts with an alpha character, followed optionally by alphanumeric, period and underscore characters.

Name$ is null for page, detail and report summary section levels.



NewPage Boolean value (0/1) to indicate if a new page is to be started when a control break or report summary occurs. Not applicable to page and detail line levels.

OutputOddPageCount Output Report Trailer only if true page count is odd (for duplex printing.) Report Trailer only.

RepeatHeader Boolean value (0/1) to indicate if the control break group header lines are to be repeated at the top of each page.

ResetPage Boolean value (0/1) to indicate whether to reset the current page number to one when the group changes. Control break level only.

Type$ Single-character code indicating the type of report section: H (header), D (detail line), F (footer). Set to null if code is invalid.

rptGroup ObjectMethods Descriptions

AddCell(LnIdx) Creates a new rptcell object using the next available sequence number. Only cells with data or formatting need to have a rptcell object created for them.

Lnidx - Sequence number of the line where the cell is located.CellCount for the specified line is incremented. Returns the object identifier if successful, 0 if not.

AddFilter(SetIdx) Creates a new RptFilter object within the RptFilterSet object specified by SetIdx using the next available sequence number. One object is created for each filter set. The sequence number can be used as the index number to identify the object when using the RemoveFilter( ) and GetFilter( ) methods.

FilterCount for the RptFilterSet object is incremented. Returns the object identifier if successful, 0 if not.

rptGroup ObjectProperties Descriptions



AddFilterSet( ) Creates a new RptFilterSet object using the next available sequence number. One object is created for each filter set. The sequence number can be used as the index number to identify the object when using the RemoveFilterSet( ) and GetFilterSet( ) methods.

FilterSetCount is incremented. Returns the object identifier if successful, 0 if not.

AddLine( ) Creates a new rptline object using the next available sequence number. It is important to add the lines in the correct sequence, as this is the sequence in which the lines in the group will be displayed in the report.

LineCount for the group is incremented. Returns the object identifier if successful, 0 if not.

CellCount(LnIdx) Returns the number of data bearing cells in a line.

Lnidx - Sequence number of the line where the cell is located.Returns 0 if the argument is invalid.

Note: A cell contains data or formatting information. Empty cells do not have an assigned object.

ClearFilters( ) Removes all RptFilterSet objects in the set and resets FilterSetCount to 0.

ClearLines( ) Removes all rptline objects from the group and resets LineCount to 0.

FilterCount(SetIdx) Returns the number of RptFilter objects in the RptFilterSet object specified by SetIdx

If SetIdx is omitted, returns the number of RptFilter objects in the first filter set.

FilterSetCount( ) Returns number of RptFilterSet objects in the set.




GetCell(LnIdx,CellIdx) Returns the identifier for a rptcell object.

Lnidx - Sequence number of the line where the cell is located.Cellidx - Sequence number of the rptcell object.This allows access to all rptcell properties. Returns 0 if the arguments are invalid.

GetCondition$

(SetIdx,FilterIdx)

Returns a string containing the ProvideX expression associated with a filter.SetIdx - Index indicating which RptFilterSet objectFilterIdx - Index of the RptFilter object

GetFilter

(SetIdx, FilterIdx)

Returns the identifier for a rptfilter object.SetIdx - Index indicating which RptFilterSet objectFilterIdx - Index of the RptFilter object

GetFilterSet(idx) Returns the identifier for a RptFilterSet object.Idx Sequence number of the RptFilterSet object.This allows access to all RptFilterSet properties and methods. Returns 0 if not successful.

GetGroupDefinition$( ) Returns a formatted string based on section information. The format of the string is that used to define a BREAK= entry in the report definition file. Returns null if the information in the rptgroup object is invalid.Format for the page header section:Header PGFormat for control break group headers:Header nn Name [OPT=PH]nn is the control break level number. OPT= is optional, P indicates NewPage property is set, H indicates RepeatHeader property is set; e.g., Header 01 CompanyId OPT=H

Format for the detail line section:Detail L1Format for control break group footers:Footer nn Namenn is the control break level number; e.g., Footer 01 CompanyId




Format for the Report Summary section:Footer 00 [OPT=P]OPT= is optional, P indicates NewPage property is set.Format for the filler section:FillerFormat for the page footer section:Footer PGFormat for the report header section:Header RP [OPT=PTBCF+]OPT= is optional and indicates which properties are set: P=NewPage, T=IncludePageHeader, B=IncludePageFooter, C=CenterContents, F=BlankPageToFollow, +=CountPage Format for the report trailer section:Footer RP [OPT=PTBCOF]OPT= is optional and indicates which properties are set: P=NewPage, T=IncludePageHeader, B=IncludePageFooter, C=CenterContents, O=OutputIfOddPageCount, F=FillToBottom Returns null if the information in the rptgroup object is invalid.

GetLine(idx) Returns the identifier for a rptline object.

idx - Sequence number of line within the group.

This allows access to all rptline properties and methods. Returns 0 if the arguments are invalid.

LineCount( ) Returns the number of lines in the section.




RemoveCell(LnIdx,CellIdx) Removes a rptcell object from the section.

Lnidx - Sequence number of the line in which the cell is located.

Cellidx - Sequence number of the cell to be removed.

If a rptcell object is removed, the sequence number of the rptcell objects with higher sequence numbers are adjusted down. CellCount is decremented for the line. Returns the object identifier if successful, 0 if not.

RemoveFilter

(SetIdx, FilterIdx)

Removes a rptfilter object.SetIdx - Index indicating which RptFilterSet objectFilterIdx - Index of the RptFilter object

RemoveFilterSet(idx) Removes a RptFilterSet object.

Idx - Sequence number of the object to be removed.

If a RptFilterSet object is removed, the sequence number of the RptFilterSet objects with higher sequence numbers are adjusted down. FilterSetCount is decremented. Returns the object identifier if successful, 0 if not.

RemoveLine(idx) Removes a rptline object from the section.

idx - Sequence number of line to be removed.

If a rptline object is removed, the sequence number of the rptline objects with higher sequence numbers are adjusted down.

Removes all rptcell objects associated with the line. LineCount is decremented for the section. Returns the object identifier if successful, 0 if not.




SetGroupDefinition(Def$) Assigns rptgroup properties based on a formatted string. Returns 1. The format of the string is that used to define a BREAK= entry in the report definition file.

Def$ Formatted string containing the section information:

Format for the page header section:Header PGFormat for control break group headers:Header nn Name [OPT=PH]nn is the control break level number. OPT= is optional, P indicates NewPage property is set, H indicates RepeatHeader property is set; e.g., Header 01 CompanyId OPT=H

Format for the detail line section:Detail L1Format for control break group footers:Footer nn Namenn is the control break level number; e.g., Footer 01 CompanyId

Format for the Report Summary section:Footer 00 [OPT=P]OPT= is optional, P indicates NewPage property is set.Format for the filler section:FillerFormat for the page footer section:Footer PGFormat for the report header section:Header RP [OPT=PTBCF+]OPT= is optional and indicates which properties are set: P=NewPage, T=IncludePageHeader, B=IncludePageFooter, C=CenterContents, F=BlankPageToFollow, +=CountPage




rptline

The rptline object is a data member of the rptgroup object, delegated to store and manipulate a report line definition. One object is created for each report line in the section, in the order that they are to be displayed. The pvxreport or rptgroup GetLine( ) methods can be used to retrieve the object identifier for a rptline object, which allows access to all the object’s methods and properties.

The rptline object has its own data member, the rptcell object, to define the cells in the line. It has methods to create and access these objects.

rptline Properties and Methods

Format for the report trailer section:Footer RP [OPT=PTBCOF]OPT= is optional and indicates which properties are set: P=NewPage, T=IncludePageHeader, B=IncludePageFooter, C=CenterContents, O=OutputIfOddPageCount, F=FillToBottom


rptline ObjectProperties Descriptions

Height Height of the line in points (72’s of an inch). Must be a positive number.

rptline ObjectMethods Descriptions

AddCell( ) Creates a new rptcell object using the next available sequence number. Only cells with data or formatting need to have a rptcell object created for them.

CellCount for the line is incremented. Returns the object identifier if successful, 0 if not.

CellCount( ) Returns the number of cells in a line.

Note: A cell contains data or formatting information. Empty cells do not have an assigned object.



rptcell

The rptcell object is a data member of the rptline object, delegated to store and manipulate a cell definition. One object is created for each data- or format-bearing cell in a report line. The pvxreport, rptgroup or rptline GetCell( ) methods can be used to retrieve the object identifier for a rptcell object, which allows access to all the object’s methods and properties.

rptcell Properties

GetCell (idx) Returns the identifier for a rptcell object.

idx - Sequence number of the rptcell object.

This allows access to all rptcell properties. Returns 0 if the arguments are invalid.

RemoveCell (idx) Removes a rptcell object from the section.

idx - Sequence number of the cell to be removed.

If a rptcell object is removed, the sequence number of the rptcell objects with higher sequence numbers are adjusted down.

CellCount is decremented for the line. Returns the object identifier if successful, 0 if not.

rptline ObjectMethods Descriptions

rptcell ObjectProperties Descriptions

Align$ Alignment code: L (left), C (centre), R (right)

If blank, default alignment is left.

AlternateCell Object identifier for the alternate *rpt/rptcell object which contains the definition and conditions associated with an alternate cell definition.



BackgroundColour$ The background colour of the cell can be defined in terms of RGB:n,n,n setting, or using pre-defined colour names; e.g., RGB:255,0,128.

or ... Black, Light Red, Light Green, Light Yellow, Light Blue, Light Magenta, Light Cyan, White, Dark Gray, Dark Red, Dark Green, Dark Red, Dark Yellow, Dark Blue, Dark Magenta, Dark Cyan, Light Gray.

If blank, background colour is default (White)

BottomBorder Single-digit code indicating the border at the bottom edge of the cell: 0 (none), 1 (thin), 2 (medium), 3 (thick). If blank, default is no bottom border.

Column Column in which the cell is located. The first column is column 1.

Font$ Comma separated string containing font information fontname, size[,attributes][,angle] where attributes are B (bold) or I (italic) and angle may be 0, 90 or 270; e.g.,

Verdana,-15,B

Format$ Format mask for displaying the value. May be a fixed value or expressions. Expressions are prefixed by an equal sign; e.g., =%FMT1$.

Hyperlink$ Contains the hyperlink. May be a literal value or expression. Read-only. Use SetHyperlink( ) method to set.

HyperlinkExpr$ X | F - Indicates whether Hyperlink$ contains a literal (F) or expression (X). Read-only. Use SetHyperlink( ) method to set.

HyperlinkOption$ Display option:0 = Use current browser window (default).1 = Use new browser window.Read-only. Use SetHyperlink( ) method to set.

Image$ Contains the path or url to the image. May be a literal value or expression. Read-only. Use SetImage( ) method to set.




ImageExpr$ X | F - Indicates whether Image$ contains a literal (F) or expression (X). Read-only. Use SetImage( ) method to set.

ImageOption$ Display option:

1 = Original size, align top left. 2 = Original size, centre in region. 3 = Resize to fit region. 4 = Resize with same aspect ration, align top left. 5 = Resize with same aspect ration, centre in region.

Read-only. Use SetImage( ) method to set.

JoinColumns Number of columns joined in this cell. Default is 0 if the cell is not joined.

JoinRows Number of rows joined in this cell. Default is 0 if the cell is not joined.

LeftBorder Single-digit code indicating the border at the left edge of the cell: 0 (none), 1 (thin), 2 (medium), 3 (thick). If blank, default is no left border.

RightBorder Single-digit code indicating the border at the right edge of the cell: 0 (none), 1 (thin), 2 (medium), 3 (thick). If blank, default is no right border.

TextColour$ The text colour of the cell –can be defined in terms of RGB:n,n,n setting, or using pre-defined colour names; e.g., RGB:255,0,128.

or ... Black, Light Red, Light Green, Light Yellow, Light Blue, Light Magenta, Light Cyan, White, Dark Gray, Dark Red, Dark Green, Dark Red, Dark Yellow, Dark Blue, Dark Magenta, Dark Cyan, Light Gray.

If blank, text colour is set to Default.

TopBorder Single-digit code indicating the border at the top edge of the cell: 0 (none), 1 (thin), 2 (medium), 3 (thick). If blank, default is no top border.

Value$ Fixed text value or data variable or expression whose value will be displayed in the cell.

WordWrap Indicator to wrap text in a cell. 1=On, 0=Off. Default is 0 (off).




rptcell Methods

rptcell ObjectMethods Descriptions

AddAlternateCell( ) Add an AlternateCell rptcell object to the main rptcell object. Return AlternateCell.

RemoveAlternateCell( ) Drop the AlternateCell rptcell object from the main rptcell object and set AlternateCell to 0.

SetHyperlink(Hyperlink$,Xflg$,Dis-pOpt$)

Puts an HTML hyperlink in the cell. (The associated text to be displayed on the report must be specified by setting the cell’s Format$ and Value$ properties independently.)

Where:

Hyperlink$ - Hyperlink address (may be fixed literal or expression)Xflg$ - X, F or blank (default). “X” indicates that Hyperlink$ is an expression.DispOpt$ - Display option:

0=Use current browser window (default) 1=Use new browser window

SetImage(Image-Path$,Xflg$,DispOpt$)

Puts an image in the cell. (Alternate text may be specified by setting the cell’s Format$ and Value$ properties independently.)

Where:

ImagePath$ - Path to the image (may be fixed or expression). Xflg$ - X, F or blank (default). “X” indicates that ImagePath$ is an expression.DispOpt$ - Display Option:

1 = Original size, align top left. 2 = Original size, centre in region. 3 = Resize to fit region. 4 = Resize with same aspect ration, align top left. 5 = Resize with same aspect ration, centre in region.



The following methods are only available to rptcell objects specified as AlternateCell objects:

AlternateCell rptcell Object Methods Descriptions

AddFilter (SetIdx) Creates a new RptFilter object within the RptFilterSet object specified by SetIdx using the next available sequence number. One object is created for each filter set. The sequence number can be used as the index number to identify the object when using the RemoveFilter( ) and GetFilter( ) methods.

FilterCount for the RptFilterSet object is incremented. Returns the object identifier if successful, 0 if not.

AddFilterSet( ) Creates a new RptFilterSet object. If one already exists, returns address to current.FilterSetCount is set to 1.Returns the object identifier if successful, 0 if not.

ClearFilters( ) Removes the RptFilterSet object resets FilterSetCount to 0.

FilterCount(SetIdx) Returns the number of RptFilter objects in the RptFilterSet object specified by SetIdx. If SetIdx is omitted, returns the number of RptFilter objects in the first filter set.

FilterSetCount( ) Returns the number of RptFilterSet objects in the set (1 or 0).

GetFilterSet( ) Returns the identifier for the RptFilterSet object. This allows access to all RptFilterSet properties and methods. Returns 0 if not successful.

GetCondition$(SetIdx,FilterIdx) Returns a string containing the ProvideX expression associated with a filter.

SetIdx – Index indicating which RptFilterSet object.FilterIdx – Index of the RptFilter object.

GetFilter(SetIdx,FilterIdx) Returns the identifier for a rptfilter object

SetIdx – Index indicating which RptFilterSet object.FilterIdx – Index of the RptFilter object.



rptcalcfield

The rptcalcfield object is a data member of the pvxreport object interface that is delegated to store and manipulate a calculated field definition. It can be used to retrieve the object identifier for a rptcalcfield object, which allows access to all the object's methods and properties.

rptcalcfield Properties and Methods

RemoveFilter(SetIdx,FilterIdx)

Removes a rptfilter object.

SetIdx – Index indicating which RptFilterSet objectFilterIdx – Index of the RptFilter object

RemoveFilterSet( ) Removes the RptFilterSet object. If the RptFilterSet object is removed FilterSetCount is set to 0. Returns the object identifier if successful, 0 if not.

AlternateCell rptcell Object Methods Descriptions

rptcalcfield ObjectProperties Descriptions

Description$ Short description for the field. (optional)

Expression$ Expression to be evaluated and loaded into the variable specified in Name$. Read-only property. Loaded using the SetExpression( ) method.

Length Maximum length of the field. Numeric fields may contain a scaling factor (e.g. 10.2 where 10 is the total length and 2 is the number of digits following the decimal point).

Name$ Variable name for the calculated field.

Type$ Data type - N or S (numeric/string). Set when Expression is loaded using SetExpression( ) or SetTranslationValue( ) methods.



rptcalcfield ObjectMethods Descriptions

AddTranslationValue([idx]) Create a new rptfilterctl object to hold the condition to be associated with the translation value. One object is created for each translation value. Also allocates storage for the translation value and an expression indicator.

idx - If omitted or set to zero, the rptfilterctl object is created using the next available sequence number. If set, the object is inserted at the sequence number indicated by idx.

The sequence number can be used as the index number to identify the object when using other methods relating to translation fields, such as GetTranslationCondition( ), GetTranslationValue$( ), etc.

TranslationValueCount is incremented.

Returns the object identifier if successful, 0 if not.

ClearTranslationValues( ) Removes all translation values, expression indicators, and rptfilterctl objects associated with the translation values.

GetTranslationCondition(idx) Returns the object ID for the specified rptfilterctl object.


Returns 0 if the sequence number is invalid

GetTranslationValue$(idx) Returns the specified translation value. May be a fixed value or an expression. See the IsTranslationValueExpression( ) method to determine the content type.

idx - Sequence number of the translation value.

Returns null if the sequence number is invalid

IsTranslationValueExpression(idx)

Returns a Boolean value (0 or 1) indicating whether the specified translation value contains an expression (1) or a fixed value (0).

idx - Sequence number of the translation value.



MoveTranslationValue(fromidx,toidx)

Changes the sequence of a translation value (i.e., value, expression indicator and rptfilterctl object sequence). The sequence of other translation values are appropriately adjusted.

fromidx - Sequence number of translation value to be moved.

toidx - Sequence number to move translation value to.

RemoveTranslationValue(idx)

Removes the rptfilterctl object and clears the translation value and expression indicator for the specified translation value.

idx - Sequence number of the translation value to be removed. Translation values with higher sequence numbers are adjusted down.

TranslationValueCount is decremented.

SetExpression(expr$) Set the expression to be evaluated and loaded into the variable specified in the Name$ property.

Returns 1 if successful, and 0 if the expression is invalid.




rptgroupfunc

The rptgroupfunc object is a data member of the pvxreport object interface, delegated to store and manipulate a group function definition. One object is created for each function. The pvxreport GetGroupFunc( ) method can be used to retrieve the object identifier for a rptgroupfunc object, which allows access to all the object’s methods and properties.

rptgroupfunc Properties and Methods

SetTranslationValue (idx, value$ [,IsExpression$ [,type$] ]

Sets the translation value at the specified sequence number.

idx - Sequence number of the translation value to be set.

value$ - Translation value. May be fixed or an expression.

IsExpression$ - "X" denotes that value$ contains an expression. "F" or null ("") denotes that Value$ contains a literal or fixed value. Optional, default is a fixed value.

type$ - "S" (string) or "N" (numeric). If the Type$ property of the rptcalcfield class has already been set, then this value is ignored. If it has not been set, then this value is used to set it.

TranslationValueCount( ) Returns the number of translation values associated with a translation field.


rptgroupfunc ObjectProperties Descriptions

Element$ The data element to be used in the function calculation. This must start with an alphanumeric, optionally followed with alphanumeric, period or underscore characters. No trailing $ for string elements. Set to null if the element name is invalid.

Format$ The format mask for displaying the value.

Function$ The name of the group function. Possible values: AVERAGE, COUNT, MAXIMUM, MINIMUM, SUM. Set to null if the function name is invalid.



Type$ Single-character code to indicate whether the function element contains string or numeric data: S (string/text), N (numeric/computational). Set to null if code is invalid.

rptgroupfunc ObjectMethods Descriptions

GetGroupFunctionDefinition$( ) Returns a formatted string based on rptgroupfunc properties. The format of the string is that used to define a Function= entry in the report definition file.

Format for COUNT function: COUNT:format; e.g.,COUNT:###,##0.

Format for other functions:

FuncName([convert] element):format; e.g.,AVERAGE (Balance):###,###,##0.00MAXIMUM(Convert CustID):000000

Returns null if the information in rptgroupfunc object is invalid.

GetGroupFunctionVariable$ (LevelID$)

Returns the name of the group function variable based on the current Function$, Element$ and Type$ properties and the given LevelID$

LevelID$ - 00 = Report Summary level 01 - 16 = Control break group level

DL - Detail line level

Example: _SUMDLN_Balance, _AVG03N_Amount,_CTR00N

rptgroupfunc ObjectProperties Descriptions



rptsort

The rptsort object is a data member of the pvxreport object interface, delegated to store and manipulate a sort segment definition. One object is created for each segment in the sort order, and the creation sequence must match the sort order sequence. The pvxreport GetSortItem( ) method can be used to retrieve the object identifier for a rptsort object, which allows access to all the object’s methods and properties.

rptsort Properties

SetGroupFunctionDefinition$ (Def$) Assigns rptgroupfunc properties based on a formatted string. The format of the string is that used to define a Function= entry in the report definition file. Returns 1.

Def$ Formatted string containing the group function information:

Format for COUNT function: COUNT:format; e.g.,COUNT:###,##0.

Format for other functions:

FuncName([convert] element):format; e.g.,AVERAGE (Balance):###,###,##0.00MAXIMUM(Convert CustID):000000

rptgroupfunc ObjectMethods Descriptions

rptsort ObjectProperties Descriptions

SegmentName$ Name of the table element used in the sort order. This must start with an alpha character, optionally followed by alphanumeric, period or underscore characters. Set to null if invalid.

Type$ Single-character code to indicate whether the sort order segment contains string or numeric data: S (string/text), N (numeric/computational). Default is S.

Length Positive numeric value indicating the number of characters in the sort element to be used to determine sort order.

Order$ Single-character code to indicate the sequence of the segment: A (ascending), D (descending).



rptparam

The rptparam object is a data member of the pvxreport object interface, delegated to store and manipulate a parameter definition. One object is created for each parameter. The pvxreport GetGroup( ) method can be used to retrieve the object identifier for a rptparam object, which allows access to all the object’s methods and properties.

rptparam Properties

IgnoreCase Boolean value indicating whether case should be ignored when sorting the segment. Default is 1; i.e., a case-insensitive sort.

rptsort ObjectProperties Descriptions

rptparam ObjectProperties Descriptions

Default$ Pre-set value that will automatically be loaded. (optional).

Description$ Prompt to be displayed in the user interface which is presented when the report is generated. This should explain to the user what value to enter and its format.

Length Maximum length of the value to be entered by the user. Must be a positive number. Set to 0 if invalid.

Maximum$ Maximum value that can be entered. (optional).

Minimum$ Minimum value that can be entered. (optional).

Name$ Name of the data variable to store the parameter value–used mainly in formulas and filter definitions. This must start with an alpha character, optionally followed by alphanumeric , period or underscore characters.

Maximum 30 characters. Set to null if invalid.

Type$ Single-character code to indicate whether the parameter value is a string or numeric value: S (string/text), N (numeric/computational).

Value$ Current value of the parameter.



rptfilterset

The rptfilterset object is a data member of the pvxreport, rptline and rptcell objects, delegated to store and manipulate a filter set definition. One object is created for each filterset. The pvxreport GetFilterSet( ) method can be used to retrieve the object identifier for a rptfilterset object, which allows access to all the object's methods and properties. This object contains a group of rptfilter objects that make up the individual filters belonging to the set.

rptfilterset Properties and Methods

rptparam ObjectMethods Descriptions

SetParameter (Value$)

SetParameter (Value)

Sets the value of a parameter.

Value$ may be used to set string or numeric values.

Value may be used to set numeric values.

rptfilterset ObjectProperties Descriptions

FilterCount Number of rptfilter objects in the filterset.

Option$ Contains an “A” (Accept) or “R” (Reject).

In the case of a data filter, this indicates whether to accept or reject a data record if all conditions in the filterset are true. In the case of detail lines and cell formats, this indicates whether or not to use a particular line or cell format if the conditions are true.

rptfilterset ObjectMethods Descriptions

AddFilter( ) Creates a new RptFilter object using the next available sequence number. One object is created for each filter definition. The sequence number can be used as the index number to identify the object when using the RemoveFilter( ) and GetFilter( ) methods.

FilterCount is incremented. Returns the object identifier if successful, 0 if not.

ClearFilters( ) Removes all RptFilter objects in the set and resets FilterCount to 0.



rptfilter

The rptfilter object is a data member of the pvxreport object interface, delegated to store and manipulate a data filter definition. One object is created for each filter. The pvxreport GetFilter( ) method can be used to retrieve the object identifier for a rptfilter object, which allows access to all the object’s methods and properties.

rptfilter Properties and Methods

FilterCount( ) Returns the number of RptFilter objects in the set.

GetCondition$(idx) Returns a string containing the ProvideX expression associated with a filter.Idx - Sequence number of the filter.|Returns null if the sequence number is invalid.

GetFilter(idx) Returns the identifier for a RptFilter object.Idx - Sequence number of the RptFilter object.This allows access to all RptFilter properties and methods. Returns 0 if not successful.

RemoveFilter(idx) Removes a RptFilter object.Idx - Sequence number of the object to be removed. If a RptFilter object is removed, the sequence number of the RptFilter objects with higher sequence numbers are adjusted down. FilterCount is decremented. Returns the object identifier if successful, 0 if not.

rptfilterset ObjectMethods Descriptions

rptfilter ObjectProperties Descriptions

CompareValue$ Value to be used for comparison in the condition test. Some conditions use more than one comparison value. Indicate which CompareValue$ is being accessed by setting the ValNo property to the index number of the desired CompareValue$ property. Default is the first CompareValue$, until the ValNo index is otherwise set.



ConditionCode Code number (1-12) indicating the type of condition: 0 (none), 1 (equal to), 2 (not equal to), 3 (less than), 4 (greater than) , 5 (less than or equal to), 6 (greater than or equal to), 7 (between..and.. inclusive), 8 (between..and..exclusive), 9 (any of..,..,..,etc.), 10 (none of …, …, etc.), 11(contains), 12 (starts with).

IsCaseSensitive Boolean value (0/1) indicating whether the condition test should be case sensitive or not.

ValNo Index (1-8) to indicate which CompareValue$ property is being accessed. Valid indices are based on the type of condition. Default is 1, until otherwise set.

Variable$ Name of the table element to be used in the condition test. This must start with an alpha character, optionally followed by alphanumeric, period or underscore characters.

Names of elements containing string values must be terminated by a $ character.

Set to null if invalid.

If the name of a string element is assigned, the IsCaseSensitive property is set to 1.

rptfilter ObjectMethods Descriptions

GetCompareValue$(Idx) Returns the value of the CompareValue$ property whose index is give.

idx - Index of CompareValue$ property. Assigned to ValNo property.

Returns null if the index value is invalid.

rptfilter ObjectProperties Descriptions



rptdesigner

The rptdesigner object is a data member of the pvxreport object interface, delegated to store and save Report Designer options.

rptdesigner Properties and Methods

GetCondition$( ) Returns the condition in the form of a ProvideX expression; e.g., if the following properties are set:

Variable=CompanyId$ConditionCode=1IsCaseSensitive=0ValNo=1CompareValue$=CompanyNumber$

…then the return value would be:

CompanyId$=CompanyNumber$

Returns null if the information in the rptfilter object is invalid.

SetCompareValue(Idx,Val$) Assigns a value to the CompareValue$ property whose index is given.

idx - Index of CompareValue$ property. Assigned to ValNo property.

Val$- value to be assigned to specified CompareValue$ property.

Returns 1 if successful, or 0 if the index value is invalid.

rptfilter ObjectMethods Descriptions

rptdesigner Properties Descriptions

AutoDisplayHTML Boolean value (0/1). When on, the Report Designer will automatically display any reports generated in HTML format with the default browser. Default 0.

AutoDisplayPDF Boolean value (0/1). When on, the Report Designer will automatically display any reports generated in PDF format with the default PDF reader. Default 0.



ColumnWidth Default column width in inches or cm., depending on Metric setting. If set to 0, the Designer default will be ½ inch or 1 cm.

Font$ The default font to used for new reports. Default Arial,-15

Metric Boolean value (0/1). When on, the ruler on the Designer display will use metric (centimeter) units. Default is inches.

NumericFormatMask$ The default numeric format mask to use for group functions. Default is "###,###,##0.00-".

RowHeight Default row height in inches or cm., depending on Metric setting. If set to 0, the Designer will use a calculated value based on the size of the default font set for the current report.

TestMode Boolean value (0/1). When on, the Designer will generate a report in test mode. Test mode restricts the number of records processed when a report is generated. A processed record is one that is included in the report, i.e. it has not been rejected by the filtering process. Default is 0.

TestRecords The maximum number of records to be processed when a report is generated in test mode. If set to 0 (default), the entire data source is processed.

SaveOption Boolean value (0/1). When on, the above option values will be saved to the pvxreport.ini file. Default is 0.

rptdesigner Methods Descriptions

LoadOptions( ) Loads the option values from the client or local pvxreport.ini file. (Windows only.)

SaveOptions( ) Saves the option values in the client or local pvxreport.ini file. (Windows only.)

rptdesigner Properties Descriptions

Report Writer Report Writer User Interfaces


Report Writer User Interfaces B MKB MK

Report Writer Us er Int er faces

The Report Writer can interface with two optional user-created objects, one that can supply additional generic logic for processing reports, and another that can be used to output the data generated by a report definition. It also interfaces with optional user-created programs or panels. This functionality is explained below:

Logic Object Interface, p.95Custom Output Object Interface, p.100Custom Parameter Interfaces, p.104

Logic Object Interface

The Report Writer can interface with an optional user-created object which supplies additional generic logic for processing reports. Specifically, the user object has properties and methods, as specified under User Interface Specifications, that can be used to set up the execution environment, load variables, specify new system variables, adjust the report format, manipulate data, and reset the environment. The user object may also have additional miscellaneous methods that can be referenced in the report definition.

The user logic object must either reside under the *rpt directory and be named *rpt/userlogic.pvc, or the global variable %RW_UserLogic$ can be pre-loaded with the object name before the Report Writer object (*rpt/pvxreport) is created. The object named in %RW_UserLogic$ will take precedence. If a *rpt/userlogic.pvc logic object exists or one is specified in %RW_UserLogic$, it will be used to process all reports.

User Interface Specifications: *rpt/userlogic.pvc The user logic object will be created during the On_Create logic of the *rpt/pvxreport report object, and dropped during the On_Delete logic. It must be defined with specific properties and functions, although additional local properties and On_Create/On_Delete logic may be included as desired. The required methods may contain simple stubs if there is no additional logic associated with them.

The user interface must include the following properties and methods:

Function Initialize( )The *rpt/pvxreport object will invoke this method in its On_Create logic. It is useful for setting up the execution environment for defining or generating a report.

Function Reset( )The report object will invoke this method in its On_Delete logic. It can be used to reset the execution environment, if desired.

Topics

Report Writer


Function UpdateReport(Rpt)This method is invoked as the first step in the *rpt/pvxreport object StartReport( ) method. At this point a report definition is contained within the report object, and the object identifier for *rpt/pvxreport (Rpt) is passed to UpdateReport( ) so it has access to change the definition before the report is generated.

Function UpdateData$(Data$,Iolist$)This method is used within the *rpt/pvxreport object ReadData$( ) method, immediately after a record is read. If the file being read has an external key, then this method is invoked passing the unparsed key data and the key iolist. The method is also invoked passing unparsed record data and the compiled data iolist. This method can be useful for translating unprintable characters that could exist in the data. Data can be manipulated on the unparsed record level, or on a field by field level by reading the data from the record into the fields (i.e. READ DATA FROM data$ to IOL=Iolist$). This method returns a string value consisting of the manipulated record. If the data was parsed into fields and manipulated, it must be reassembled into a record to be returned; i.e., REC(Iolist$).

Property UserVariableCountFunction GetUserVariable$(idx)Function GetUserVariableDescription$(idx)Function GetUserVariableLength(idx)Function GetUserVariableValue$(idx)The user object contains a series of properties and methods that allow the user to specify user variables that can be appended to the list of standard system variables that are supported by the Report Writer. If any user variables are defined, then they will be included wherever standard system variables may be accessed, such as the Field Selection list of the Report Designer where they can be dragged and dropped on the report layout, or in formula definitions where they can be included as part of the formula.

The UserVariableCount property must be set with the number of user variables to be defined, and methods must be defined to return information concerning each variable:

GetUserVariable$(idx) Returns the variable name.GetUserVariableDescription$(idx) Returns a short description of the variable.GetUserVariableLength(idx) Returns the maximum length of its value.GetUserVariableValue$(idx) Returns its current value as a string (must

convert numerics).The user variable in question is identified by an index (i.e., information concerning the first variable will be returned if the index passed to the method is one, etc.).

Report Writer


Other MethodsThe developer may include additional methods that can be accessed in the report using UserLogic as the object identifier. For example, the user could include a method in the user object to format the page number in a particular way:

FUNCTION UserPage$(PageNumber$)=MSG("PAGE")+PageNumber$

Then, in the report definition, the formula UserLogic'UserPage$(_Page$) could be used in one of the page header cells to format the page number.

*rpt/rptuserlogic Template The following template is supplied for the *rpt/userlogic object, constructed with stubs for all required methods.

! *rpt/rptuserlogic.pvc - Template for the UserLogic object ! (c) 2005 Sage Software Canada Ltd. ! _____________________________________________________________________ ! DEF CLASS "*rpt/rptuserlogic" ! PROPERTY UserVariableCount ! FUNCTION Initialize()=1 FUNCTION Reset()=1 FUNCTION UpdateReport(Rpt)=1 FUNCTION UpdateData$(data$,iolist$)=data$ FUNCTION GetUserVariable$(idx)="" FUNCTION GetUserVariableDescription$(idx)="" FUNCTION GetUserVariableLength(idx)=0 FUNCTION GetUserVariableValue$(idx)="" ! END DEF

When creating the *rpt/userlogic object, it is recommended that the class definition include a LIKE "*rpt/rptuserlogic" statement. This means that stubs are present for methods that are not required, and the user need only supply properties and methods for which there is additional logic. It also ensures that stubs will be present for new methods that may be required in future enhancements.

Following is a sample *rpt/userlogic object:

! Userlogic.pvc - Sample Report User Logic object!________________________________________________________________________! DEF CLASS "*rpt/userlogic" CREATE REQUIRED! LIKE "*rpt/rptuserlogic"! PROPERTY UserVariableCount! LOCAL UserVariableName$

Report Writer


LOCAL UserVariableDescription$ LOCAL UserVariableLength LOCAL User$ LOCAL

TRN_TBL$=$FF3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B202122232425262728292A2B2C2D2E2F303132333435363738393A3B3C3D3E3F404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F606162636466666768696A6B6C6D6E6F707172737475767778797A7B7C7D7E7F808182838485868788898A8B8C8D8E8F909192939495969798999A9B9C9D9E9FA0A1A2A3A4A5A6A7A8A9AAABACADAEAFB0B1B2B3B4B5B6B7B8B9BABBBCBDBEBFC0C1C2C3C4C5C6C7C8C9CACBCCCDCECFD0D1D2D3D4D5D6D7D8D9DADBDCDDDEDFE0E1E2E3E4E5E6E7E8E9EAEBECEDEEEFF0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF$

! FUNCTION Initialize()Initialize FUNCTION UpdateReport(Rpt)Update_Report FUNCTION UpdateData$(data$,iolist$)=TBL(data$,TRN_TBL$) FUNCTION GetUserVariable$(idx)Get_User_Variable_Name FUNCTION GetUserVariableDescription$(idx)Get_User_Variable_Description FUNCTION GetUserVariableLength(idx)Get_User_Variable_Length FUNCTION GetUserVariableValue$(idx)Get_User_Variable_Value!________________________________________________________________________! END DEF!________________________________________________________________________!On_Create: UserVariableCount=3 ! Set the number of user variables here DIM UserVariableName$[1:UserVariableCount]; UserVariableName$[1]="CompanyName$"; UserVariableName$[2]="CompanyCode$"; UserVariableName$[3]="VersionNumber" ! Dimension and load the variable

name array DIM UserVariableDescription$[1:UserVariableCount]; UserVariableDescription$[1]="Company Name"; UserVariableDescription$[2]="Company Code"; UserVariableDescription$[3]="Version Number" ! Dim and load the

description array DIM UserVariableLength[1:UserVariableCount]; UserVariableLength[1]=40; UserVariableLength[2]=3; UserVariableLength[3]=4.2 ! Dimension and load the variable max length

array! Initialize other work variables IF TCB(88) \ THEN CALL "[wdx]*windx.utl;get_val","WHO",User$ \ ELSE User$=WHO RETURN!________________________________________________________________________! Initialize:

Report Writer


%ReportDirectory$="R:\rpt\" RETURN 1! Update_Report: ENTER Rpt! Only BigBoss gets to see the individual balances IF User$="BigBoss" \ THEN RETURN 1 gc=Rpt'GroupCount() FOR gc grp=Rpt'GetGroup(gc) lc=grp'LineCount() FOR lc line=grp'GetLine(lc) cc=line'CellCount() FOR cc cell=line'GetCell(cc) IF cell'format$<>"" AND POS("BALANCE"=UCS(cell'value$)) \ THEN cell'value$="------------",cell'format$="" IF cell'AlternateCell>0 AND cell'AlternateCell'format$<>"" AND

POS("BALANCE"=UCS(cell'AlternateCell'value$)) \ THEN

cell'AlternateCell'value$="------------",cell'AlternateCell'format$=""

NEXT cc NEXT lc NEXT gc RETURN 1! Get_User_Variable_Name: ENTER idx IF idx<1 OR idx>UserVariableCount \ THEN RETURN "" \ ELSE RETURN UserVariableName$[idx]! Get_User_Variable_Description: ENTER idx IF idx<1 OR idx>UserVariableCount \ THEN RETURN "" \ ELSE RETURN UserVariableDescription$[idx]! Get_User_Variable_Length: ENTER idx IF idx<1 OR idx>UserVariableCount \ THEN RETURN 0 \ ELSE RETURN UserVariableLength[idx]! Get_User_Variable_Value: ENTER idx IF idx<1 OR idx>UserVariableCount \

Report Writer


THEN RETURN "" SWITCH idx CASE 1 v$="ABC Company" ! supply the value of the user variable BREAK CASE 2 v$="ABC" BREAK CASE 3 v$="7.00" BREAK END SWITCH RETURN v$

Custom Output Object Interface

The Report Writer interfaces with optional user-created output objects that can be used to output the data generated by a report definition. When a report is defined, the user will be able to select Custom Output from the list of Output Destinations (Printer/Clipboard/HTML document/Viewer/Custom Output) in the File menu. This may be either a default custom output destination, or one specific to the report. If Custom Output is selected for a report, a specific custom output object may be specified for the report (File > Specify Custom Destination), or if none is specified, a default custom output object will be used.

To define a custom output destination, the custom object must either reside under the *rpt directory and be named *rpt/useroutput.pvc, or the global variable %RW_UserOutput$ must be pre-loaded with the object name before the Report Writer object (*rpt/pvxreport) is created. The object named in %RW_UserOutput$ will take precedence.

If the report is defined as using Custom Output and the output destination does not exist, the report will not be generated and status of 0 will be returned by the SetOutputDevice( ) method or RunReport( ) method, depending on the methodology for generating the report.

A user-created custom output object must have properties and methods as specified under User Interface Specifications.

To specify that a report is to be sent to a custom output object, the Custom Output item must be selected from the File > Output Destination menu. In this case, the default output object will be used, unless a different object is specified in the Custom Output Object Interface accessed from the File > Specify Custom Destination menu, or from the Options menu or toolbar button. See also Custom Interfaces, p.32.

Report Writer


User Interface Specifications: *rpt/useroutput.pvc A custom output object must be defined with specific properties and functions, although additional properties and On_Create/On_Delete logic may be included as desired. The required methods may contain simple stubs if there is no additional logic associated with them.

The user interface must include the following properties and methods:

Property MaxLinesThis property contains the maximum number of lines that can be printed on a page. For example, the *rpt/rptprinter object sets ‘lpi’(6) (six lines per inch) and then determines the maximum number of lines using the MXL( ) function. This value is used to determine the location of the footer, and for paging. In the case where vertical location is irrelevant, such as clipboard or html output, this should be set to zero.

Property NoChannelBoolean value indicating output is not being sent to an output channel, such as clipboard output. (1 = No output channel, 0 = Output channel used)

Property NoPagingBoolean value to indicate whether paging is to occur or not. (1 = No Paging, 0 = Paging)

Property PrinterCompatibleBoolean value indicating whether or not the output is printer compatible, and if page properties (such as orientation and margins) are to be set up when the output device is opened. This is applicable for output to *winprt*, *pdf*, and *viewer*. This should be set to zero for html or clipboard output, for example.

Property Destination$This property contains the destination file name to be opened for output. May contain "*winprt*", "*viewer*", "*pdf*", a file pathname, or blank for output to the clipboard.

Property DestinationOption$Set this property with the desired output option, i.e. AsIs, Default, Normal, Display, Overwrite, etc.

Property DestinationFile$Use this property to set the output file to be specified in the FILE= clause of the open option for *winprt* or *pdf*. Leave blank if not applicable.

Function Initialize(Rpt )The object identifier for the report object (*rpt/pvxreport) is passed as an argument for this function. This makes report information available to the custom output object. This method can be used to initialize variables or do various setup

Report Writer


procedures required by the object. For example, set properties, set default font, clear the clipboard, output html header information, etc. The *rpt/pvxreport object will invoke this method in its StartReport( ) method.

Function GetIolist$(GroupIdx,LineIdx)Builds and returns an IOLIST to be used to output the line specified by the group index and line index. The contents of the IOLIST are based on information stored in the *rpt/rptcell objects belonging to the line. Refer to the Object-Oriented Interface, p.45, for details on *rpt/rptcell object properties and methods. This method is invoked in the StartReport( ) method of the *rpt/pvxreport object.

Function FormFeed( )Output a formfeed. If the output does not contain formfeeds, such as output to the clipboard, this method can be defined using a simple stub; e.g., FUNCTION FormFeed( )=1.

Function TranslateSpecialChars$(Record$)This method can be used to modify raw record data. For example, it can be used to translate or replace certain characters in the data content to be output. In the case of HTML output, for instance, characters such as “&”, “<” and “>” have special meaning within the HTML tags, so they must be translated in a special way within the data so that they are recognized and handled properly when the HTML output is processed.

Function PrintLine(Line$)Output a line of the report.

Function Close( )Can be used to perform any wrap-up procedures that are required. For example, output closing tags for HTML output, output the final report to the clipboard, etc. This method is invoked by the FinishReport( ) method of the *rpt/pvxreport object.

*rpt/rptoutput Template The following template is supplied for the *rpt/useroutput object, constructed with stubs for all required methods.

! *rpt/rptoutput.pvc - Template for the UserOutput object ! (c) 2005 Sage Software Canada Ltd. !_______________________________________________________________________ ! DEF CLASS "*rpt/rptoutput" ! LOCAL Rpt ! *rpt/pvxreport object identifier ! PROPERTY MaxLines ! PROPERTY NoChannel

Report Writer


PROPERTY NoPaging PROPERTY PrinterCompatible ! PROPERTY Destination$ ! *winprt*, *viewer*, *pdf* or a file name PROPERTY DestinationOption$ ! AsIs, Default, Normal,Display, Overwrite,

etc. PROPERTY DestinationFile$ ! Specified in FILE= option for *winprt* or

*pdf*) ! FUNCTION Initialize(Rpt) ENTER Rpt RETURN 1 ! FUNCTION GetIolist$(GroupIdx,LineIdx)="" FUNCTION FormFeed()=1 FUNCTION TranslateSpecialChars$(r$)=r$ FUNCTION PrintLine(Line$)=1 FUNCTION Close()=1 ! END DEF

When creating the *rpt/useroutput object, it is recommended that the class definition include a LIKE "*rpt/rptuseroutput" statement. This means that stubs are present for methods that are not required, and the user need only supply properties and methods for which there is additional logic. It also ensures that stubs will be present for new methods that may be required in future enhancements.

Alternately, custom output objects can be based on any of the existing output objects, *rpt/rptprinter.pvc, *rpt/rpthtml.pvc or *rpt/rptclipboard.pvc. For example, the following sample object which outputs a PDF file is based on *rpt/rptprinter.pvc:

DEF CLASS "outputpdf" LIKE "*rpt/rptprinter" PROPERTY Destination$="*pdf*" PROPERTY DestinationFile$=%PDFfile$ END DEF

To generate a report defined using the above sample output object, outputpdf would have to be specified as the custom output object for that report when the report was defined. Then code such as the following can generate the report directly to a PDF file and display it:

%PDFfile$="c:\tmp\sample.pdf" r=NEW("*rpt/pvxreport") r'RunReport("MyReport.pvr") DROP OBJECT r SYSTEM_HELP %PDFfile$

Report Writer


Custom Parameter Interfaces

The Report Writer interfaces with optional user-created programs or panels that are used to process external parameters that are used with the report. The developer interface may consist of a program (and optional label) to be called or a library and panel to be processed. If a Parameter Interface is not specified, or if a program or panel is specified and cannot be found, then the default will be the generic parameter interface panel supplied with the Report Writer.

Parameter Program InterfaceTo interface with a program, the Program setting must be selected as the Parameter Interface in the Report Options Custom Interface folder. The program specification may include a program entry point (separated by a semi-colon) and may be a fixed value or expression.

At run-time, the report generator will invoke the parameter program from within the AcceptParameters( ) method (which is invoked by the RunReport(file$) and RunReport(file$,channel) methods) using the CALL directive:

CALL ParameterProgram$, STR(Rpt), Status$, P1$, P2$,...,P18$

The user parameter program therefore requires a corresponding ENTER statement:

ENTER Rpt$, Status$ [,P1$,...,P18$],ERR=StmntRef

Where:

Rpt$ RptObjID=num(Rpt$)Object identifier for the pvxreport object. This makes the existing rptparam objects available to be accessed for information.

Status$ Return status may be loaded with 4 values: Null ("") or "0" - Cancel the report."1" - Parameter values have been successfully retrieved and placed in argument fields P1$ through P18$, as required. These values will automatically be loaded into the rptparam objects by the Report Writer."2" - Parameter values have been successfully retrieved and directly loaded into the existing rptparam objects by the parameter program.

P1$,…,P18$ Optional arguments to pass the parameter values specified for the report (see Parameters, p.10). The order of the parameters and argument values correspond. Arguments may be used to receive default parameter values set up when the report parameters are defined, as well as to return the final parameter values to the report generator.

If Status$ is set to "1", these values must be returned, as the values will be loaded into the rptparam objects by the AcceptParameters( ) method that called the program.

Report Writer


Sample Parameter Program 1:

In this example, the report definition has two parameters defined to indicate the start and end point of a date range. These parameters are retrieved by reading two records from a serial file. Besides the required arguments to contain the pvxreport object ID and the status value, the ENTER statement in the parameter program must contain two arguments to pass these values back, in the order required by the report definition. Within the program, the Status$ variable is initialized to "0", which would cause the report to be aborted if an error occurred when the file was opened. After the successful retrieval of the parameter values, Status$ is set to "1" to indicate success, and to flag the fact that the AcceptParameters( ) method should proceed to load these values into the internal rptparam objects for use by the report generator.

! Retrieve StartDate$ and EndDate$ parameters from a serial fileENTER Rpt$, Status$, StartDate$, EndDate$, ERR=*NEXTStatus$="0"OPEN(1,ERR=Done)"DateRange.txt"READ RECORD StartDate$READ RECORD EndDate$CLOSE(1)Status$="1"Done: EXIT

Sample Parameter Program 2:

In this example, the report definition includes two parameters called StartDate and EndDate, to indicate the start and endpoint of a date range. These parameters are retrieved by reading two records from a serial file. The report parameters will be set right in the program code, so only the first two arguments, the pvxreport object ID and the status value, are required. In this case, the SetParameter( ) method is used to set the parameter, using the parameter name to identify it. Status$ is set to "2" to indicate success, and to flag the fact that the new parameter values have been set.

!Retrieve StartDate and EndDate parameters from a serial fileENTER Rpt$, Status$, err=*NEXTRpt=num(Rpt$)Status$="0"OPEN(1,ERR=Done)"DateRange.txt"READ RECORD SDate$

The AcceptParameters( ) method will not validate these values, as it will be assumed they are correct. The number of parameter value arguments loaded is determined by the number of parameters set up in the report definition. If Status$ is set to "2", these arguments are not required to return parameter values, as it will be assumed that the rptparam objects were updated by the user program logic.

Report Writer


READ RECORD EDate$CLOSE(1)Rpt'SetParameter("StartDate",SDate$)Rpt'SetParameter("EndDate",EDate$)Status$="2"Done: EXIT

Parameter Panel InterfaceTo interface with a panel, the Panel setting must be selected as the Parameter Interface in the Report Options Custom Interface folder. The panel specification requires the entry of a panel library and the name of a panel. The panel should be defined as a ’dialogue’ in the panel’s header attributes.

At run-time, the report generator will invoke the parameter panel from within the AcceptParameters( ) method (which is invoked by the RunReport(file$) and RunReport(file$,channel) methods) as follows:

PROCESS ParmPanel$, ParmLibrary$, STR(Rpt), Status$, P1$,...,P18$

Where:

When processing a panel, the report object identifier can be retrieved from ARG_1$ (e.g., Rpt=num(ARG_1$), and status can be returned in ARG_2$ (e.g., ARG_2$="1"). Parameter default values are passed to the panel process using ARG_3$ through ARG_20$. Final parameter values may be returned in ARG_3$ through ARG_20$ as well; e.g., ARG_3$=StartDate$, ARG_4$=EndDate$.

ParmPanel$ Name of the panel to be processed.

ParmLibrary$ Library path.

Rpt$ See Parameter Program Interface, p.104.

Status$ See Parameter Program Interface, p.104.

P1$,…,P18$ See Parameter Program Interface, p.104.

report writer-v8

Documents