Enhancing an HTML Webpage With a Procedure

In this section:

You can enhance the functionality of your webpage by enabling you to include HTML commands in your procedures using the Dialogue Manager -HTMLFORM command. -HTMLFORM supports all standard HTML elements, including character styling, hyperlinks, graphic images, tables, forms, and frames. You can combine a procedure and HTML commands in the following ways:

Referring to an External Webpage

How to:

You can include HTML commands in your procedure by specifying an HTML webpage in your procedure.

Syntax: How to Refer to an External Webpage From a Procedure

-HTMLFORM filename

where:

filename

Is the HTML file that contains the target webpage. The name of the HTML file must be in uppercase letters.

  • In UNIX and Windows, this is the 8-character file name of the HTML file that contains the webpage. The file extension must be .HTM, not .HTML.
  • In Windows and UNIX, the file extension must be .HTM.
  • In z/OS, this is either the member name of a file in the PDS allocated to ddname WWWHTM, or it is the ddname of a sequential file. The file is variable blocked (VB).
  • An HTML file called by -HTMLFORM must reside in a path defined by the WebFOCUS Reporting Server.

If you use separate HTML files, you cannot use Dialogue Manager commands and variables in the file. However, the WebFOCUS escape sequences, described in Including Variables in an HTML Webpage, can be used.

Embedding HTML Commands in a Procedure

How to:

You can include HTML commands in a procedure by embedding those commands in a procedure.

Note: The -RUN command cannot be included in the lines between the -HTMLFORM BEGIN and -HTMLFORM END commands.

Syntax: How to Embed HTML Commands in a WebFOCUS Procedure

-HTMLFORM BEGIN
       .
       .
       .
-HTMLFORM END

where:

-HTMLFORM BEGIN

Indicates the beginning of HTML commands.

-HTMLFORM END

Indicates the end of HTML commands.

Note: All lines that are not Dialogue Manager commands are assumed to be HTML.

All Dialogue Manager variables referenced within the -HTMLFORM BEGIN and -HTMLFORM END commands are evaluated, even within comment tags, so you should either assign them a default value or escape the ampersand symbol using a pipe character (|) so that it is not interpreted as the start of a variable name. For example, in the following sample, the ampersand is escaped using the pipe character so that the variable definition in the comment is not evaluated:

-HTMLFORM BEGIN
<HTML>
<HEAD>
<SCRIPT>
/* escaping the ampersand in a comment: &|x=y */
</SCRIPT>
</HEAD>
<BODY>
Test variable in Javascript comments
</BODY>
</HTML>
-HTMLFORM END

Example: Including a Webpage in a Procedure

The following procedure contains a report request and the -HTMLFORM command, which customizes the webpage the report is displayed on. The report is centered in the browser window, and displays with the Arial font in blue.

TABLE FILE SHORT
SUM PROJECTED_RETURN
BY COUNTRY
ON TABLE HOLD AS SHORT FORMAT HTMTABLE
END
-HTMLFORM BEGIN
<HTML><HEAD><STYLE>TD {FONT-FAMILY: ARIAL; COLOR: BLUE; }</STYLE></HEAD>
<BODY><DIV ALIGN="CENTER">
!IBI.FIL.SHORT;
</DIV></BODY></HTML>
-HTMLFORM END

The following webpage is produced:

Embedding a Procedure in an HTML Webpage

How to:

You can embed one or more reports or HTML files into your webpage using -HTMLFORM commands.

Procedure: How to Embed a Report in an HTML Webpage

To embed a report into a webpage created with -HTMLFORM commands:

  1. Create a report procedure that retrieves and formats the report data, then saves the output from each report in a separate temporary file. The following syntax is used in the report procedure:
    ON TABLE HOLD FORMAT HTMTABLE AS reportname

    Note: The temporary file created for the output is not available to the user.

  2. If you are using an external HTML file to display the webpage that embeds the report, the report procedure must specify the file using the following command:
    -HTMLFORM filename

    Note: If you are not using an external HTML file, the HTML commands for the webpage can reside in the same file using -HTMLFORM BEGIN and -HTMLFORM END to separate the HTML commands from the rest of the procedure.

  3. In the HTML commands for the webpage, specify the location where each report or HTML file is to be displayed, using an HTML escape code. The escape code syntax is
    !IBI.FIL.reportname

    where:

    reportname

    Is the name of the report file to embed in the Web page.

    Note: The designated report name can be up to 512 characters.

    Files embedded with the !IBI.FIL escape sequence can contain other escape sequences. If reference is made to a file that does not exist, an error message is returned.

Example: Embedding Multiple Reports Into One HTML Webpage

This example shows how to embed multiple HTML reports into one HTML webpage. The following code generates three reports, each consisting of the same automotive data that is sorted three different ways; by country, by body type, and by manufacturer.

TABLE FILE CAR
"REPORT 1 - BY COUNTRY"
PRINT CAR MODEL BODYTYPE
BY COUNTRY
ON TABLE HOLD FORMAT HTMTABLE AS REPORT1
ON TABLE SET STYLE *
TYPE=HEADING,STYLE=BOLD,COLOR=RED,$
ENDSTYLE
END
TABLE FILE CAR
"REPORT 2 - BY BODY TYPE"
PRINT CAR MODEL COUNTRY
BY BODYTYPE
ON TABLE HOLD FORMAT HTMTABLE AS REPORT2
ON TABLE SET STYLE *
TYPE=HEADING,STYLE=BOLD,COLOR=BLUE,$
ENDSTYLE
END
TABLE FILE CAR
"REPORT 3 - BY MANUFACTURER"
PRINT MODEL BODYTYPE COUNTRY
BY CAR
ON TABLE HOLD FORMAT HTMTABLE AS REPORT3
ON TABLE SET STYLE *
TYPE=HEADING,STYLE=BOLD,COLOR=GREEN,$
ENDSTYLE
END
-HTMLFORM BEGIN
!IBI.FIL.REPORT1;
!IBI.FIL.REPORT2;
!IBI.FIL.REPORT3;
-HTMLFORM END

The following images show the three reports that are embedded into one HTML document:

Embedding Variables Into One HTML Webpage

This example generates a report consisting of product codes and quantities, and displays the current time and date found in Dialogue Manager system variables. The following explains how the elements required to display this report are combined. The numbers to the left of the example apply to the notes that follow.

Step 1 - First.htm

Set up the webpage that will hold the report. This webpage must be saved in a directory within EDAPATH or APPPATH in order for WebFOCUS to find it. The following file is called first.htm:

   <HTML>
   <BODY> 
2. Time: 
3. !IBI.FIL.&TOD <BR> 
2. Date: 
3. !IBI.FIL.&DATE <BR>
   <HR SIZE=5> 
4. <!--WEBFOCUS TABLE UPPER--> 
   </BODY>
   </HTML>

Note: The HTML comment line must be closed with the ---> characters or a single > character and should not have any other HTML tags within it.

Step 2 - Amper.fex

Create your report request:

    TABLE FILE GGORDER
    SUM QUANTITY BY PCD
    IF PCD EQ 'B$$$'  
1. ON TABLE HOLD FORMAT HTMTABLE AS UPPER
    END 
5. -RUN 
6. -HTMLFORM first

Step 3 - Launch.htm

Create a webpage, which launches the report procedure:

<HTML>
<BODY>
<P>
<P>
<A HREF="/ibi_apps/WFServlet?IBIF_ex=amper">Click here.</A>
</BODY>
</HTML>

When the procedure and both webpages have been created, the webpage that launches the procedure can be called from the browser. When the procedure is launched, the report is executed:

  1. The HOLD command extracts report output into a temporary file, from which it can be sent to a webpage.
  2. The code Time: and Date: specify text that will appear above the report on the webpage.
  3. The HTML comments are read by WebFOCUS and identify the variables to be printed on the webpage.
  4. The HTML comment is read by WebFOCUS and identifies the report to be displayed. This table name is the name assigned in the HOLD command in the procedure. On the webpage, WebFOCUS substitutes the designated report for the corresponding code.
  5. The -RUN command runs the report.
  6. The Dialogue Manager command merges the report output with the contents of first.htm, the HTML file that contains your webpage.

The following webpage is generated:

Including Variables in an HTML Webpage

How to:

In WebFOCUS, you can use Dialogue Manager variables to insert variable values in a webpage. This is done by specifying the variable name using a WebFOCUS escape code. You can use the value of a variable either as text on an HTML webpage or as a value in an HTML form input field. You can include a variable that you have created, or system variables like &DATE (today's date) and &TOD (time of day). A single webpage can contain many variable substitution tags.

To use a variable in a webpage created with the -HTMLFORM commands, the variable must first be declared with -SET or -DEFAULT. See Customizing a Procedure With Variables for information on using variables.

Syntax: How to Return the Value of a Variable in an HTML Webpage

<!--WEBFOCUS VAR [&]&variable-->

or

!IBI.{AMP|GLB}.[&]&variable;

where:

AMP

Returns the value of a local variable.

GLB

Returns the value of a global variable.

variable

Is a local or global variable.

Note: The HTML comment line must be closed with the ---> characters or a single > character and should not have any other HTML tags within it.

Syntax: How to Return the Length of a Variable in an HTML Webpage

!IBI.{AML|GLL}.[&]&variable;

where:

AML

Returns the length of a local variable.

GLL

Returns the length of a global variable.

Syntax: How to Use a Variable in a Webpage

The syntax for a local variable in a form input field is

<INPUT TYPE=TEXT NAME=variable     VALUE="!IBI.AMP.variable;">

where:

variable

Is the variable name.

When making substitutions, the full string is replaced, starting with the exclamation point (!) and ending with the semicolon (;). You cannot include variables whose values include internal escape sequences in your command stream.