Extending Metadata With Reporting Objects

Reference: Reporting Object Tool Quick Launch Toolbar

The Reporting Object tool Quick Launch toolbar is a static menu whose commands apply to the entire Reporting Object, not simply to the particular component that you have selected. The following table describes each command in the Reporting Object tool Quick Launch toolbar.

Shortcut Keys	Command	Description
None	Reporting Object tool main menu	Launches a menu allowing you to Save, Save As, Run, and Exit.
Ctrl+S	Save	Saves the Reporting Object.
Ctrl+Z	Undo	Undoes the last action.
Ctrl+Y	Redo	Repeats the last action.
None	View code	Displays Reporting Object code in a read-only window.
Ctrl+R	Run	Runs the Reporting Object.

Reference: Reporting Object Tool Ribbon

The Reporting Object tool ribbon is a menu whose commands apply to what you have selected, whether that is the Reporting Object as a whole, a particular component, or an individual example of a component. For example, a particular filter or filter group, if you have selected one, rather than selecting the entire Filter component.

The following table describes each command on the Reporting Object tool ribbon.

Button	Command	Description
	New	Creates a new join, DEFINE statement, filter, or WHERE statement.
	Open	Launches InfoAssist to create or edit a report or chart, or launches the appropriate tool to create or edit a join, DEFINE statement, filter, or WHERE statement.
	Edit	Opens component source code in the text editor.
	Properties	Renames the selected filter or filter group.
	Run	Runs the selected component.
	Delete	Deletes the selected item.
	Delete All	Deletes all items of the type selected, for example, all WHERE statements, all filters in a particular group, or all filters in every group if the Filter component itself is selected.

Procedure: How to Create a Reporting Object

From the WebFOCUS Hub or WebFOCUS Home Page, open the Workspaces area.
Select the Workspace in which you want to create the Reporting Object, click the +Create button, point to Data, and click Reporting Object.
The Reporting Object tool opens in a new browser window, with an Open dialog box.
Select a Master File and click OK.

The Reporting Object tool interface appears.

Procedure: How to Edit a Reporting Object

From the WebFOCUS Hub or WebFOCUS Home Page, in the Workspaces area, right-click the Reporting Object and select Edit.

Note: Double-clicking the Reporting Object runs the Reporting Object rather than allowing you to edit it.

Procedure: How to Save a Reporting Object

Press Ctrl+S or click the Save icon on the Quick Launch toolbar.

The Save dialog box opens.
Type the name of the new Reporting Object in the Title field and click OK.

From now on, clicking Save or pressing Ctrl+S saves the Reporting Object without launching the Save dialog box.

Running a Reporting Object From the Browser

In this section:

Expected Behavior of Running a Reporting Object

You can run a Reporting Object or any individual component of it from the browser. You can run a Reporting Object in the following ways:

Select the object in the Reporting Object tool and click Run, or right-click the object and select Run.
Right-click the Reporting Object in the Workspaces view and select Run or Run Deferred.

The Run option in the Reporting Object tool is enabled regardless of the setting of the Only Run as a Deferred Report property.

Expected Behavior of Running a Reporting Object

When you select and run a Reporting Object, the expected behavior is as follows:

When you define a Report or Chart component, all components of the Reporting Object run.
When you define a Report and Chart component, an HTML page opens, which enables you to select which component to run.
When you define filters in a Reporting Object, an HTML page opens, which enables you to select from the defined filters of the Reporting Object.
When you define parameters in a report or chart and the Reporting Object Prompt for Parameters property is specified, an HTML page opens, which prompts you for parameter values.
Reporting Object components are validated prior to run time. This means that errors are found and corrected more easily, since errors in individual components are detected prior to run time.

If you attempt to run a Reporting Object that is created without using the Report or Chart component, you receive the message:

Your request did not return any output to display.

Possible causes:
- No data rows matched the specified selection criteria.
- Output was directed to a destination such as a file or printer.
- An error occurred during the parsing or running of the request.

Properties of a Reporting Object

From the WebFOCUS Hub or WebFOCUS Home Page, in the Workspaces area, you can view or edit the properties of a Reporting Object by right-clicking the object and selecting Properties. The Properties panel opens, displaying properties of the selected file.

Components of a Reporting Object

A Reporting Object may contain any of the following types of components, which are run in the order of precedence, as listed:

Preprocessing Other (custom code that runs before all other components)
Joins
DEFINE statements
Filters, when applicable
WHERE statements
Report or chart templates
Postprocessing Other (custom code that runs after all other components)

Users using the Reporting Object to create a report do not see the DEFINE statements, WHERE statements, or JOIN commands defined in the Reporting Object, which are issued automatically every time a user accesses the Reporting Object. However, the report or chart components, including headers, footers, and styling features, are visible to authorized users who can use them to create their own customized report.

The filters defined in the Filter component are applied only if the user of the Reporting Object activates them when the report or chart based on the Reporting Object is run.

Preprocessing Other Component

Reference:

Considerations for Amper Auto Prompting With the Preprocessing and Postprocessing Other Components
Creating a Reporting Object That Uses a HOLD File

The Preprocessing Other component contains custom code that must run before all other components. You can use the text editor in the component to create and edit code or to paste the code that you have copied from another application.

To create or edit a Preprocessing Other component, do one of the following:

Double-click the component.
Select the component and click Edit on the ribbon.
Right-click the component and select Edit.

The Preprocessing Other text editor appears.

See Creating Reports With WebFOCUS Language for more information about using the WebFOCUS language to code procedures.

Note:

Syntax and error checking is not performed on the commands that you type until the Reporting Object is run.
Commands in the Preprocessing Other component should not return a displayable answer set.
InfoAssist previews in the Report component and the Chart component are disabled if the Preprocessing Other component contains the syntax:
```
-OLAP ON
```
To avoid this issue, enable OLAP through the Reporting Object properties instead of the Preprocessing Other component. For more information on the Reporting Object properties, see Properties of a Reporting Object.

Reference: Considerations for Amper Auto Prompting With the Preprocessing and Postprocessing Other Components

When using Amper Auto prompting, users may be prompted to supply amper variable values for parameters that the private user content does not reference. These scenarios are directly related to the internal processing of reports created using a Reporting Object.

Auto prompting considerations and expected behavior must be understood when referencing amper variables within a Reporting Object. For information on the Amper Auto prompting facility, see Developing Reporting Applications . The specification of values for the amper variables in the Reporting Object Other component using –DEFAULT, –DEFAULTH, or –SET commands will assign a default value for amper variables in a report request to avoid a FOC error for not specifying a value. A consideration for –DEFAULTH and –SET is that Amper Auto prompting does not prompt for amper variables that have values assigned using –DEFAULTH and –SET.

Whether a user is prompted by the Amper Auto prompting facility for amper variables assigned a default value using the –DEFAULT command is dependent on the setting of the WebFOCUS Client configuration parameter, IBIMR_prompting. When IBIMR_prompting is set to XMLPROMPT, users are prompted for amper variable values, and default values are displayed in fields in which the default values have been specified. When IBIMR_prompting is set to XMLRUN, users are not prompted for values when all amper variables have been assigned a default value. For more information on setting the IBIMR_prompting parameter, see WebFOCUS Security and Administration .

Reference: Creating a Reporting Object That Uses a HOLD File

Suppose that your company has a data warehouse and you need a Reporting Object that uses an extract from that data warehouse. In your Preprocessing Other component, you create a HOLD file from the data warehouse, and then you use that HOLD file in each Reporting Object component. You can clear the JOIN command and delete the HOLD file in the Postprocessing Other component so that it is not mistakenly used again the next time that the Reporting Object is used.

This task has the following steps:

Create a HOLD file in the Preprocessing Other component.
Create a new Join component with two joins.
Use the Report component to create a new report in InfoAssist.
Clear the JOIN command and delete the HOLD file in the Postprocessing Other component.
Run the Reporting Object, and then view the object source to verify that the output is correct.
Verify that the HOLD file does not exist in the location in which it was created.

Example: Creating a HOLD File With the Preprocessing Other Component

Create a Reporting Object with the baseapp and ibisamp selected as the application paths and employee as the Master File.
For more information on creating a Reporting Object, see Properties of a Reporting Object.
Select the Preprocessing Other component and click Edit.

Type the following code:

APP HOLD IBISAMP
TABLE FILE EMPLOYEE
PRINT EMPLOYEE.EMPINFO.DEPARTMENT AS 'NEWDEP'
EMPLOYEE.EMPINFO.CURR_SAL AS 'NEWCURR_SAL'
BY EMPLOYEE.EMPINFO.EMP_ID AS 'EMP_ID'
BY EMPLOYEE.EMPINFO.HIRE_DATE AS 'NEWHIRE_DATE'
ON TABLE HOLD AS WINFILE FORMAT FOCUS INDEX EMP_ID
END

Click Save, and then close the text editor.
To verify that the component works properly, select the Preprocessing Other component and click Run.
The following output is produced:
```
0 NUMBER OF RECORDS IN TABLE= 12 LINES= 12
```

Example: Creating a New Join Component With Two Joins

Select the Join component and click New.
The Join component is prefilled with the data from the employee Master File.
Click Add New, select the winfile Master File, and click OK.
Click the Add New button, select the jobfile Master File, and click OK.
Click OK to close the Join tool, saving your changes.

Click View Code in the Reporting Object Quick Launch toolbar to review the code.

The following code for the Join component displays:

-*COMPONENT=Join_J001
JOIN EMPLOYEE.EMPINFO.EMP_ID IN IBISAMP/EMPLOYEE
TO UNIQUE WINFILE.SEG01.EMP_ID IN IBISAMP/WINFILE TAG J001 AS J001
END
-*COMPONENT=Join_J002
JOIN EMPLOYEE.PAYINFO.JOBCODE IN IBISAMP/EMPLOYEE
TO UNIQUE JOBFILE.JOBSEG.JOBCODE IN IBISAMP/JOBFILE TAG J002 AS J002
END

Example: Creating a Report With the Report Component

Double-click the Report component.
InfoAssist is launched.
Drag the NEWCURR_SAL measure from the Data pane to the canvas.
Drag the EMP_ID dimension to the left of the NEWCURR_SAL column in the canvas, and select Drop as sort.
Drag the NEWHIRE_DATE dimension to the left of the NEWCURR_SAL column in the canvas, and select Drop as sort.
Drag the NEWDEP dimension to the left of the NEWCURR_SAL column in the canvas, and select Drop as sort.
The report is displayed as a table with four columns, sorted by EMP_ID.
Save the report and exit InfoAssist.
To verify that the component works properly, click Run on the Quick Launch toolbar.
The report that you created in InfoAssist is displayed in the browser.

Example: Deleting the Join in the Postprocessing Other Component

Select the Postprocessing Other component and click Edit.
Type the following:
```
JOIN CLEAR *
? JOIN
```
Click Save, and then click Exit.
To verify that the Reporting Object works properly, click Run on the Quick Launch toolbar.
The report that you created in InfoAssist is displayed in the browser.
Right-click the report webpage and select View source.
Note: Depending on your browser, information may display differently.

Scroll to the bottom of the source window.

The following comment is displayed:

<!--
0 NUMBER OF RECORDS IN TABLE= 12 LINES= 12
0 NUMBER OF RECORDS IN TABLE= 12 LINES= 12
0 HOLDING HTML FILE ON PC DISK ...
JOINS CURRENTLY ACTIVE
HOST                           CROSSREFERENCE
FIELD        FILE      TAG     FIELD     FILE      TAG AS ALL WH
-----        ----      ---     -----     ----      --- -- --- --
EMPLOYEE.EM&gt;EMPLOYEE        WINFILE.SEG&gt; WINFILE J0 J0 Y N
EMPLOYEE.PA&gt;EMPLOYEE        JOBFILE.JOB&gt; JOBFILE J1 J1 Y N
0 NO JOINS CURRENTLY IN EFFECT
-->

Joins

How to:

Create a Join
Delete a Join
Rename a Join
View or Edit Join Syntax in a Text Editor

A join is a temporary connection between two or more data sources that share at least one common field. After you join two data sources, each time that WebFOCUS retrieves a record from the first data source (the host file), it also retrieves the matching records from the second data source (the target file).

For more information on joining data sources, see the WebFOCUS InfoAssist User’s Manual.

Note:

When you join two TIBCO FOCUS® data sources, the target file field must be indexed or the join must be a WHERE-based join. If you attempt to link to a non-indexed target file, the Reporting Object tool offers you the opportunity to create a WHERE-based join. For more information on creating WHERE-based joins, see Join Group in the WebFOCUS InfoAssist User’s Manual.
Since every procedure creates a new session on the Reporting Server when it is run, the duration of your connection is always limited to a single procedure. Therefore, any join issued at the beginning of a procedure is in effect only for those report requests that are called in the same procedure.

Procedure: How to Create a Join

Right-click the Joins component and select New, or select the Join component and click New on the ribbon.

The Join tool opens, displaying the data source associated with the Reporting Object.
Create a join using the Join tool.

For more information on using the Join tool, see Join Group in the WebFOCUS InfoAssist User’s Manual.
When you are finished, click OK to return to the Reporting Object tool.

Procedure: How to Delete a Join

To delete a join, right-click the join and select Delete, or select the join and click Delete on the Quick Launch toolbar.

Procedure: How to Rename a Join

In the Join tool, select a join by clicking its connector line, and then click Edit on the Join toolbar.

The Edit Join dialog box opens.
Type a new description in the Description box and click OK to return to the Join tool.

The new description appears under the Join component in the Reporting Object tool. The internal name used for the join remains the same name assigned to the join when you created it.

Procedure: How to View or Edit Join Syntax in a Text Editor

Select the join and click Edit on the ribbon, or right-click the join and select Edit.

The join code is displayed in a text editor.
Make the desired changes and click Save to return to the Reporting Object tool. To exit without making any changes, click Close.

Virtual Fields (DEFINE Statements)

How to:

Create a Virtual Field
Edit a Virtual Field
View or Edit a Virtual Field in the Text Editor
Delete a Virtual Field

A virtual field is a field whose value is not stored in the data source but can be calculated from the data that is there. A virtual field takes up no storage space. It is created only when a user accesses the Reporting Object that includes the virtual field.

You use the Define tool to create a virtual field. Using this tool, you specify the virtual field name and format, and the expression that defines the field. An expression enables you to combine fields, constants, predefined functions, and operators into an operation that produces a single value. When you define a virtual field, you must specify a field format type, length, and appropriate display options.

For more information about defining fields, see Data Tab in the WebFOCUS InfoAssist User’s Manual.

Procedure: How to Create a Virtual Field

Right-click the Defines component and select New, or select the Define component and click New on the ribbon.

The Define tool dialog box opens, as shown in the following image.
Create a virtual field using the Define tool.

For more information about the Define tool, see Data Tab in the WebFOCUS InfoAssist User’s Manual.
Click OK to save the virtual field and return to the Reporting Object tool.

The virtual field now appears in the field list when a user accesses this Reporting Object.

Note:

The field list shown in the Define tool is not updated to display new virtual fields until you exit from the Define tool and reopen it. If you are creating a virtual field (DEFINE statement) that uses a previously created virtual field in the expression, you must save the first virtual field before creating the second one.
To save the first virtual field, exit from the Define tool by clicking OK. Reopen the Define tool to create the second field. Alternatively, you can type the name of the first virtual field in the expression instead of selecting it from the field list. In this case, you do not need to exit and reopen the Define tool.
Since every procedure creates a new session on the Reporting Server when it is run, the duration of your connection is always limited to a single procedure. Therefore, any DEFINE statements issued at the beginning of a procedure are in effect only for those report requests that are called in the same procedure.

Procedure: How to Edit a Virtual Field

Existing virtual fields appear under the Defines node, as shown in the following image.

Right-click the virtual field that you want to edit and select Open, or select the virtual field and click Open on the ribbon.

The Define tool dialog box opens, displaying the selected field.
Make changes to the field name, expression, or format, and click OK to return to the Reporting Object tool.

Procedure: How to View or Edit a Virtual Field in the Text Editor

Right-click the virtual field that you want to view or edit as text and select Edit, or select the virtual field and click Edit on the ribbon.
The Text Editor opens, displaying the selected field.
Make changes to the field name, expression, or format, and click OK to return to the Reporting Object tool.

Procedure: How to Delete a Virtual Field

Right-click the virtual field that you want to delete and select Delete, or select the virtual field and click Delete on the ribbon.
To delete all virtual fields at once, right-click the Defines component and select Delete All, or select the component and click Delete All on the ribbon.

Filters

How to:

Create a Filter Group
Define a Filter
Edit a Filter
Rename a Filter or Filter Group
Delete a Filter or a Filter Group
View or Edit a Filter in the Text Editor

Reference:

Filter Considerations With Amper Auto Prompting

Filters enable users to quickly select predefined criteria that limit the data included in a report or chart. Filters are selection criteria (WHERE statements) that you create for users, who then select the filters needed to limit the data in a report or chart without having to create their own selection criteria.

In order to create a filter, you must create the filter group and define the filters that make up the group.

Note: The Undo and Redo functions are not available for the Filter component until you have created at least one filter.

For more information about filters, see the Using Filters to Customize the Display of Data topic in the WebFOCUS InfoAssist User’s Manual.

Procedure: How to Create a Filter Group

Right-click the Filters component and select New, or select the Filter component and click New on the ribbon.

The Reporting Object Filter Group dialog box opens.
In the Filter Group Name field, type a descriptive name for the filter group folder.

Make the filter group name as explicit as possible, because users depend on this name to select the correct filter to apply to their reports.
Click OK.

You are returned to the Reporting Object tool. The filter group folder appears below the Filter component node.

Procedure: How to Define a Filter

Right-click the Filter group to which you would like to add a filter and select New, or select the Filter group folder and click New on the Quick Launch toolbar.

The Reporting Object Filter dialog box opens.
In the Filter Name field, type a descriptive name for the filter and click Add New if you plan to create multiple filters, or click OK if you plan to create only one filter.

Make the filter names as explicit as possible, because users depend on these names to select the correct filter to apply to their reports.

The Advanced Filter dialog box opens, as shown in the following image.
Use the Advanced Filter dialog box to create the filter.

For more information about defining filters, see Data Tab in the WebFOCUS InfoAssist User’s Manual.
When you have created the filter, click OK.

If you clicked Add new in step 2, the New Filter dialog box opens. If you clicked OK in step 2, you are returned to the Reporting Object tool.

Procedure: How to Edit a Filter

Existing filters appear under the Filter group beneath the Filters node, as shown in the following image.

Right-click the filter that you want to edit and select Open, or select the filter and click Open on the ribbon.

The Advanced Filter dialog box opens, displaying the selected filter.
Make your changes and click OK to return to the Reporting Object tool.

Procedure: How to Rename a Filter or Filter Group

Right-click the filter or filter group that you want to rename and select Properties, or select the filter or filter group and click Properties on the ribbon.
Type the new filter or filter group name in place of the current one and click OK.

Procedure: How to Delete a Filter or a Filter Group

Right-click the filter or filter group that you want to delete and select Delete, or select the filter or filter group and click Delete on the ribbon.
To delete all filters at once, right-click the Filter component and select Delete All, or select the component and click Delete All on the ribbon.

Procedure: How to View or Edit a Filter in the Text Editor

Right-click the filter that you want to view or edit as text and select Edit, or select the filter and click Edit on the ribbon.

The text editor opens, displaying the selected filter.
Make your changes and click OK to return to the Reporting Object tool.

Reference: Filter Considerations With Amper Auto Prompting

When Amper Auto prompting is used (Prompt for Parameters is selected in the Reporting Object properties), there are scenarios in which users are prompted to provide amper variable values in selection criteria (WHERE statements) in the Reporting Object that the user did not save with the report. This is due to the internal processing of reports created from Reporting Objects. You can avoid this issue by using the Filter component to predefine selection criteria for users to include in reports. Only the filter or filters that users select for inclusion in their reports are evaluated by the WebFOCUS Amper Auto prompting facility.

Selection Criteria (WHERE Statements)

How to:

Create Selection Criteria

WHERE statements or selection criteria, restrict the data retrieved to only those records that meet the conditions that you specify. Filters are selection criteria that run when the user selects the filter in WebFOCUS. Other selection criteria run when the user opens the Reporting Object, preventing data values that do not meet the criteria from being available to the user.

For more information on WHERE statements, see Field Tab in the WebFOCUS InfoAssist User’s Manual.

Procedure: How to Create Selection Criteria

Right-click the Where Statements component and select New, or select the component and click New on the ribbon.

The New Filter dialog box opens.
Double-click the red text or press F12 to edit the WHERE statement.

For more information on creating selection criteria, see the Using Filters to Customize the Display of Data topic in the WebFOCUS InfoAssist User’s Manual.
When you have created the selection criterion, click OK to return to the Reporting Object tool.

Report Component

The Report component creates a report template and saves it in a Reporting Object. Authorized users can use the report template to create a report that suits their needs and then save the new report.

To create a report template, double-click the Report component, or right-click the component and select Open. InfoAssist opens, allowing you to create a report template.

For more information on using InfoAssist, see the WebFOCUS InfoAssist User's Manual.

Note:

To open the report source code in the text editor instead of InfoAssist, right-click the Report component and select Edit. Manual changes to the code may make the report incompatible with InfoAssist.
Syntax and error checking is not performed on the commands that you type until the Reporting Object is run.
If the Reporting Object contains both a report and a chart, the user is asked whether to run the object as a report or chart. The Reporting Object cannot be run simultaneously as both.
When Amper Auto prompting is used (Prompt for Parameters is selected in the Reporting Objects properties), there are scenarios in which users are prompted to provide amper variable values in selection criteria (WHERE statements) in the Reporting Object that the user did not save with the report. This is due to the internal processing of reports created from Reporting Objects. You can avoid this issue by using the Filter component to predefine selection criteria for users to include in reports. Only the filter or filters that users select for inclusion in their reports are evaluated by the WebFOCUS Amper Auto prompting facility.

Chart Component

The Chart component works exactly like the Report component. The Chart component creates a chart template and saves it in a Reporting Object. Authorized users can use the chart template to create a chart that suits their needs and then save the new chart.

To create a chart template, double-click the Chart component, or right-click the component and select Open. InfoAssist opens, allowing you to create a chart template.

For more information on using InfoAssist, see the WebFOCUS InfoAssist User's Manual.

Note:

To open the chart source code in the text editor instead of InfoAssist, right-click the Chart component and select Edit. Manual changes to the code may make the chart incompatible with InfoAssist.
Syntax and error checking is not performed on the commands that you type until the Reporting Object is run.
If the Reporting Object contains both a report and a chart, the user is asked whether to run the object as a report or chart. The Reporting Object cannot be run simultaneously as both.
When Amper Auto prompting is used (Prompt for Parameters is selected in the Reporting Object properties), there are scenarios in which users are prompted to provide amper variable values in selection criteria (WHERE statements) in the Reporting Object that the user did not save with the report. This is due to the internal processing of private reports created from Reporting Objects. You can avoid this issue by using the Filter component to predefine selection criteria for users to include in reports. Only the filter or filters that users select for inclusion in their reports are evaluated by the WebFOCUS Amper Auto prompting facility.

Postprocessing Other Component

The Postprocessing Other component contains custom code that must run after all other components. You can use the text editor in the component to create and edit code, or to paste the code that you have copied from another application.

To create or edit a Postprocessing Other component, double-click the component, or select the component and click Edit on the ribbon. Alternatively, right-click the component and select Edit. The Postprocessing Other dialog box opens.

SeeCreating Reports With WebFOCUS Language for more information about using the WebFOCUS language to code procedures.

Note:

Syntax and error checking is not performed on the commands that you type until the Reporting Object is run.
Commands in the Postprocessing Other component should not return a displayable answer set.
InfoAssist previews in the Report component and the Chart component are disabled if the Postprocessing Other component contains the syntax:
```
-OLAP ON
```
To avoid this issue, enable OLAP through the Reporting Object properties instead of the Postprocessing Other component. For more information on the Reporting Object properties, see Properties of a Reporting Object.

For information on Amper Auto Prompting, see Considerations for Amper Auto Prompting With the Preprocessing and Postprocessing Other Components.