Inserting a Procedure or StyleSheet File Into Another Procedure With -INCLUDE

How to:

Reference:

Using the -INCLUDE command, you can insert a report procedure (.fex) or StyleSheet file (.sty) within another report procedure (.fex). Partial code can also be inserted. A partial procedure might contain heading text, or code that should be included at run time based on a test in the calling procedure.

The inserted procedure and StyleSheet files can be located in the WebFOCUS Repository or in an application directory on the Reporting Server. However, the syntax varies depending on the location of the inserted files and the calling procedure.

Note: A StyleSheet attribute named INCLUDE can also be used in a report request to apply a StyleSheet file that is stored separately from the report procedure file. The INCLUDE attribute, which can only be used for StyleSheet files, is not the same as the -INCLUDE command described in this topic.

For information on creating report requests and StyleSheet files, see the Creating Reports with WebFOCUS Language manual.

Reference: Uses for -INCLUDE

The -INCLUDE command can be used for the following:

  • Controlling the environment. For example, the inserted procedure may set variables, such as server name or user name, before the calling procedure continues execution.
  • As a security mechanism. The included procedure can be encrypted and a direct password set.
  • Shortening the code when there are several possible procedures that may be inserted. For example, the command -INCLUDE &NEWLINES could be used to determine the inserted procedure, reducing the number of GOTO commands.
  • Reusing sections of code used throughout the application, such as standard headings and footings. This enables changes made in a single module to affect the entire application.
  • Inserting a StyleSheet file.

Reference: Obtaining the Full IBFS Path Reference for a Repository Procedure

When you create a report procedure or StyleSheet file in the Repository, a unique path and file name reference is created, based on the Workspace in which the report is created and the file name and type specified. Note that there are file naming rules that replace most non-alphanumeric characters and modify the file name, when necessary.

To use the -INCLUDE command to insert a report procedure or StyleSheet file located in the Repository, you usually specify the full IBFS path to it. The only exception is when the file to be inserted and the calling procedure are stored in the same Repository folder. In that scenario, you can specify a relative path in the -INCLUDE command, as described in Insert a Repository Procedure File or StyleSheet File Using a Relative Path.

The full IBFS path information, including file name, can be obtained by right-clicking the file on the WebFOCUS Home Page and clicking Properties.

The following image shows the Properties dialog box for a report procedure (.fex), with the full path.

Syntax: How to Insert a Reporting Server Procedure or StyleSheet File Into Another Reporting Server Procedure

The following syntax illustrates how to insert a procedure or StyleSheet file located in an application directory on the Reporting Server into another report procedure located in an application directory on the Reporting Server.

-INCLUDE [appname[/subapp...]/filename[.ext]

where:

appname[/subapp...]

Is the application directory path on the Reporting Server in which the server procedure or StyleSheet file is located. If the application directory path is not specified, the file must be on the application path of the Reporting Server.

filename[.ext]

Is the name of the procedure or StyleSheet file located on the Reporting Server. The file extension is optional when a report procedure (.fex) is referenced. When incorporating a StyleSheet file, specify the .sty extension.

If you do not use the appname/filename type of path, you can use a file system path.

  • On UNIX or Windows, filename must specify the absolute path and file name for the inserted procedure. For example, F:\\ibi\apps\sales\headings.fex.
  • On z/OS, the included file must reside in the FOCEXEC library.

Example: Inserting a Reporting Server Procedure and a Reporting Server StyleSheet File

The salesrptsetup.fex procedure file, located in the ibisamp application directory on the server, contains the following commands that create two fields commonly used in the product sales reports.

DEFINE FILE GGSALES
PROFIT/D12.3= DOLLARS - BUDDOLLARS;
INVENTORY/D12 = UNITS - BUDUNITS;
END 

The salesrptstyle.sty StyleSheet file, located in the ibisamp application directory on the server, contains the following styling commands.

TYPE=REPORT,COLOR=NAVY,FONT='ARIAL',SIZE=9,GRID=OFF,$
TYPE=HEADING,LINE=1,STYLE=BOLD,SIZE=12,JUSTIFY=CENTER,$
TYPE=TITLE,BACKCOLOR=RGB(45 111 205),COLOR=WHITE,STYLE=UNDERLINE+BOLD, $
TYPE=DATA,BACKCOLOR=(WHITE RGB(235 235 255)),$
TYPE=SUBTOTAL,BACKCOLOR=RGB(163 200 236),STYLE=BOLD,$

The following procedure on the Reporting Server incorporates the procedure file salesrptsetup.fex and the StyleSheet file salesrptstyle.sty.

-INCLUDE ibisamp/salesrptsetup
TABLE FILE GGSALES
HEADING
"Regional Inventory and Profit Report"
SUM BUDUNITS UNITS INVENTORY AS 'Inventory'
BUDDOLLARS DOLLARS PROFIT AS 'Profit'
BY REGION
BY CATEGORY 
ON TABLE SET PAGE NOLEAD
ON TABLE SET STYLE *
-INCLUDE ibisamp/salesrptstyle.sty
ENDSTYLE
END

The output is shown in the following image.

Example: Inserting a Procedure File That Contains a Heading

The following request incorporates a heading, which is stored in the procedure file salehead.fex:

TABLE FILE SALES
-INCLUDE SALEHEAD
SUM UNIT_SOLD AND RETURNS AND COMPUTE
DIFF/I5 = UNIT_SOLD-RETURNS;
ON TABLE SET PAGE NOLEAD
ON TABLE SET STYLE *
GRID=OFF,$
TYPE=HEADING, COLOR=NAVY, FONT=ARIAL, STYLE=BOLD+ITALIC, SIZE=10, JUSTIFY=CENTER,$
TYPE=TITLE, COLOR=TEAL, STYLE=BOLD, SIZE=10,$
ENDSTYLE
END

The file salehead.fex, which is located in an application directory on the application path of the Reporting Server, contains the following syntax:

HEADING
"THE ABC CORPORATION"
"RETAIL SALES DIVISION"
"MONTHLY SALES REPORT"

This heading is included in the report request and displayed on the report output, as shown in the following image.

Syntax: How to Insert a Repository Procedure File or StyleSheet File Using a Full IBFS Path

The following syntax illustrates how to insert a report procedure file or StyleSheet file stored in the Repository into another report procedure, using the IBFS path.

-INCLUDE IBFS:/path/filename

where:

IBFS:/path/filename

Is the full path, including filename, of the report procedure, or the filename and extension (.sty) of the StyleSheet file. The file extension is optional when a report procedure (.fex) is referenced.

Note: This syntax can be used in a report procedure located either in the Repository or in an application directory on the Reporting Server.

Example: Inserting Repository Report Procedure and StyleSheet Files Using a Full IBFS Path

The salesrptsetup.fex file, located in the Public Workspace in the Repository, contains the following commands that create two fields commonly used in the product sales reports.

DEFINE FILE GGSALES
PROFIT/D12.3= DOLLARS - BUDDOLLARS;
INVENTORY/D12 = UNITS - BUDUNITS;
END 

The salesrptstyle.sty StyleSheet file, located in the Public Workspace in the Repository, contains the following styling commands.

TYPE=REPORT,COLOR=NAVY,FONT='ARIAL',SIZE=9,GRID=OFF,$
TYPE=HEADING,LINE=1,STYLE=BOLD,SIZE=12,JUSTIFY=CENTER,$
TYPE=TITLE,BACKCOLOR=RGB(45 111 205),COLOR=WHITE,STYLE=UNDERLINE+BOLD, $
TYPE=DATA,BACKCOLOR=(WHITE RGB(235 235 255)),$
TYPE=SUBTOTAL,BACKCOLOR=RGB(163 200 236),STYLE=BOLD,$

The following procedure incorporates the Repository procedure file salesrptsetup.fex.

-INCLUDE IBFS:/WFC/Repository/Public/salesrptsetup.fex
TABLE FILE GGSALES
HEADING
"Regional Inventory and Profit Report"
SUM BUDUNITS UNITS INVENTORY AS 'Inventory'
BUDDOLLARS DOLLARS PROFIT AS 'Profit'
BY REGION
BY CATEGORY 
ON TABLE SET PAGE NOLEAD
ON TABLE SET STYLE *
-INCLUDE IBFS:/WFC/Repository/Public/salesrptstyle.sty
ENDSTYLE
END

The output is shown in the following image.

Syntax: How to Insert a Repository Procedure File or StyleSheet File Using a Relative Path

The following syntax illustrates how to insert a report procedure file or StyleSheet file stored in the Repository into another report procedure, using a relative path. This syntax is only supported when the file to be inserted is in the same Repository folder as the calling report procedure.

-INCLUDE ./filename.ext

where:

./filename.ext

Specifies the relative path to the procedure (.fex) or StyleSheet (.sty) file to be inserted. You can only use this syntax when the file to be inserted is in the same Repository folder as the calling procedure.

Note: This syntax is not supported when running a procedure from the Reporting Server.

Example: Inserting a File Containing a Heading Using a Relative Path

The following procedure file, heading.fex, contains the following heading syntax.

HEADING
"This is the included heading file"
" "

The following procedure, include_heading.fex, is in the same Repository folder as the heading file, and contains a -INCLUDE command with a relative path to it.

TABLE FILE EMPLOYEE
-INCLUDE ./heading.fex
PRINT CURR_SAL BY LAST_NAME BY FIRST_NAME
WHERE DEPARTMENT EQ 'MIS'
ON TABLE SET PAGE NOLEAD
ON TABLE SET STYLE *
GRID=OFF,$
TYPE=HEADING, SIZE = 16, STYLE=BOLD,$
END

The output is shown in the following image.

Syntax: How to Insert a Reporting Server Procedure or StyleSheet File Using an IBFS Path

To insert a procedure or StyleSheet file located in an application directory on a Reporting Server into another procedure, using the WebFOCUS IBFS path, enter:

-INCLUDE IBFS://EDA/nodename/appname/filename.ext

where:

nodename

Is the Reporting Server node defined in the WebFOCUS Client configuration. The IBFS://EDA/ path specifies that the procedure or StyleSheet file is located on a Reporting Server.

appname

Is the application directory path on the Reporting Server in which the server procedure or StyleSheet file is located. If this path is not specified, the file must be on the application path of the Reporting Server.

filename.ext

Is the name of the procedure or StyleSheet file located on the Reporting Server. The file extension is optional when a report procedure is referenced. When incorporating a StyleSheet file, specify the .sty extension.

Note: This syntax can be used in a report procedure located either in the Repository or in an application directory on the Reporting Server.

Example: Inserting Reporting Server Report Procedure and StyleSheet Files Using an IBFS Path

The salesrptsetup.fex procedure file, located in the ibisamp application directory on the Reporting Server, contains the following commands that create two fields commonly used in the product sales reports.

DEFINE FILE GGSALES
PROFIT/D12.3= DOLLARS - BUDDOLLARS;
INVENTORY/D12 = UNITS - BUDUNITS;
END 

The salesrptstyle.sty StyleSheet file, located in the ibisamp application directory on the Reporting Server, contains the following styling commands.

TYPE=REPORT,COLOR=NAVY,FONT='ARIAL',SIZE=9,GRID=OFF,$
TYPE=HEADING,LINE=1,STYLE=BOLD,SIZE=12,JUSTIFY=CENTER,$
TYPE=TITLE,BACKCOLOR=RGB(45 111 205),COLOR=WHITE,STYLE=UNDERLINE+BOLD, $
TYPE=DATA,BACKCOLOR=(WHITE RGB(235 235 255)),$
TYPE=SUBTOTAL,BACKCOLOR=RGB(163 200 236),STYLE=BOLD,$

The following procedure incorporates the Reporting Server procedure salesrptsetup.fex and the Reporting Server StyleSheet file salesrptstyle.sty.

-INCLUDE IBFS://EDA/EDASERVE/ibisamp/salesrptsetup.fex
TABLE FILE GGSALES
HEADING
"Regional Inventory and Profit Report"
SUM BUDUNITS UNITS INVENTORY AS 'Inventory'
BUDDOLLARS DOLLARS PROFIT AS 'Profit'
BY REGION
BY CATEGORY 
ON TABLE SET PAGE NOLEAD
ON TABLE SET STYLE *
-INCLUDE IBFS://EDA/EDASERVE/ibisamp/salesrptstyle.sty
ENDSTYLE
END

The output is shown in the following image.

Syntax: How to Insert a Reporting Server Procedure or StyleSheet File Using Legacy Managed Reporting Syntax

A best practice in WebFOCUS application development is to centralize report styling and environmental setup, such as JOINs and DEFINEs, by storing them in a common workspace and defining security permissions to permit users to read and run them, but not edit or change them. However, Repository applications may need to reference report procedures and StyleSheet files that are located in an application directory on the Reporting Server.

Note: The information in this section is for legacy Managed Reporting applications that have been migrated.

Managed Reporting inserts Reporting Server procedure or StyleSheet files by using Reporting Server -INCLUDE syntax prefixed with the -MRNOEDIT command.

-MRNOEDIT -INCLUDE appname[/subapp...]/filename[.ext]

where:

appname[/subapp...]

Is the application directory path on the Reporting Server in which the server procedure or StyleSheet file is located. If the application directory path is not specified, the file must be on the application path of the Reporting Server.

filename[.ext]

Is the name of the procedure or StyleSheet file located on the Reporting Server. The file extension is optional when a report procedure (.fex) is referenced. When incorporating a StyleSheet file, specify the .sty extension.

Note: If you have a procedure that includes this legacy syntax, and you move the procedure to an application directory on the Reporting Server, you must remove the -MRNOEDIT prefix.

Example: Inserting Reporting Server Procedure and StyleSheet Files Using Managed Reporting Syntax

The following is an example of incorporating Reporting Server procedure and StyleSheet files into a Repository procedure using the -MRNOEDIT and -INCLUDE commands.

The salesrptsetup.fex procedure file contains the following commands that create two fields commonly used in the product sales reports. This file is located in the /ibi/apps/ibisamp directory on the Reporting Server.

DEFINE FILE GGSALES
PROFIT/D12.3= DOLLARS - BUDDOLLARS;
INVENTORY/D12 = UNITS - BUDUNITS;
END 

The salesrptstyle.sty StyleSheet file containing the following styling commands is located on the Reporting Server in the /ibi/apps/ibisamp directory.

TYPE=REPORT,COLOR=NAVY,FONT='ARIAL',SIZE=9,GRID=OFF,$
TYPE=HEADING,LINE=1,STYLE=BOLD,SIZE=12,JUSTIFY=CENTER,$
TYPE=TITLE,BACKCOLOR=RGB(45 111 205),COLOR=WHITE,STYLE=UNDERLINE+BOLD, $
TYPE=DATA,BACKCOLOR=(WHITE RGB(235 235 255)),$
TYPE=SUBTOTAL,BACKCOLOR=RGB(163 200 236),STYLE=BOLD,$

The following Repository procedure incorporates the salesrptsetup procedure file and the salesrptstyle StyleSheet file, both located on the Reporting Server.

-MRNOEDIT -INCLUDE ibisamp/salesrptsetup 
TABLE FILE GGSALES
HEADING
"Regional Inventory and Profit Report"
SUM BUDUNITS UNITS INVENTORY AS 'Inventory'
BUDDOLLARS DOLLARS PROFIT AS 'Profit'
BY REGION
BY CATEGORY 
ON TABLE SET PAGE NOLEAD
ON TABLE SET STYLE *
-MRNOEDIT -INCLUDE ibisamp/salesrptstyle.sty
ENDSTYLE
END

The output is shown in the following image.

Note: If you move the Repository procedure to an application directory on the server, remove the -MRNOEDIT command. For example:

-INCLUDE ibisamp/salesrptsetup

Syntax: How to Use a Server Application Directory Linked to a WebFOCUS Repository With -INCLUDE

If you configure the Adapter for WebFOCUS Client REST on the Reporting Server, you can create an application directory that is linked to your WebFOCUS Repository and use that application directory as the server path in the -INCLUDE command.

For information about configuring the Adapter for WebFOCUS Client REST, see the Adapter Administration manual. For information about linking your WebFOCUS Repository to an application on the server, see the Server Administration manual.

The following syntax illustrates how to insert a report procedure or StyleSheet file located in the WebFOCUS repository, using an application directory on the Reporting Server linked to a WebFOCUS Repository.

-INCLUDE [wfcapp[/subapp...]/filename[.ext]

where:

wfcapp[/subapp...]

Is the Repository Workspace that contains the file to be inserted, referenced using the linked server application directory (wfcapp).

filename[.ext]

Is the name of the procedure or StyleSheet file located on the Repository path. The file extension is optional when a report procedure (.fex) is referenced. When incorporating a StyleSheet file, specify the .sty extension.

Example: Using a Server Application Directory Linked to a WebFOCUS Repository With -INCLUDE

As shown in the following image, the Reporting Server has an application directory that is linked to the WebFOCUS Repository.

The name assigned to this application directory is wfc01.

The Repository Workspace named Public in the linked wfc01 application directory contains the salesrptsetup.fex file, as shown in the following image.

The salesrptsetup.fex file contains the following code that creates two fields commonly used in the product sales reports.

DEFINE FILE GGSALES
PROFIT/D12.3= DOLLARS - BUDDOLLARS;
INVENTORY/D12 = UNITS - BUDUNITS;
END 

The following report procedure on the Reporting Server incorporates the salesrptsetup.fex file using the linked application directory.

-INCLUDE wfc01/Public/salesrptsetup.fex
TABLE FILE GGSALES
"Regional Inventory and Profit Report"
SUM BUDUNITS UNITS INVENTORY AS 'Inventory'
BUDDOLLARS DOLLARS PROFIT AS 'Profit'
BY REGION
BY CATEGORY 
ON TABLE SET STYLE *
-INCLUDE ibisamp/salesrptsty.sty
ENDSTYLE
END

The output is shown in the following image.

Reference: Considerations When Using -INCLUDE With ReportCaster

From the Reporting Server, for each task within a schedule, ReportCaster supports receiving a single answer set, such as report, chart, or HTML file. Therefore, when using -INCLUDE to incorporate a procedure into a procedure that will be scheduled with ReportCaster, only one answer set should be returned. If you need to distribute multiple reports within a single document, use the Compound Report feature. For more information, see the Creating Reports With WebFOCUS Language manual.