Opening URLs with WEB.SHOW_DOCUMENT in Oracle Forms

Modern Oracle Forms applications often need to integrate with the web—whether to display reports, open online resources, or navigate to external systems. Oracle Forms provides the WEB.SHOW_DOCUMENT built-in for this purpose. It enables developers to open a specified URL in a browser window directly from the form. This tutorial explains what WEB.SHOW_DOCUMENT is, its syntax, use cases, examples, and best practices.

What is WEB.SHOW_DOCUMENT?

The WEB.SHOW_DOCUMENT built-in allows Oracle Forms to display a web page, a file, or a servlet by sending a request to the user’s web browser. Unlike the HOST built-in, which interacts with the operating system, WEB.SHOW_DOCUMENT is specifically designed for web-enabled applications.

It is widely used in Oracle Forms deployed on the web (Forms Services), where client machines access applications through a browser.

Syntax of WEB.SHOW_DOCUMENT

The general syntax is:

WEB.SHOW_DOCUMENT(url, target);

• url → A string representing the web address or file path.
• target → Specifies how and where the URL should be opened:
  • _blank → Opens in a new browser window or tab.
  • _self → Opens in the same browser frame where Forms is running.
  • _parent → Opens in the parent frame.
  • _top → Opens in the full browser window, replacing current content.

Example: Opening a Website

BEGIN
   WEB.SHOW_DOCUMENT('https://www.oracle.com', '_blank');
END;

This will open Oracle’s homepage in a new browser tab.

Example: Displaying a PDF Report

Suppose your application generates reports stored on the application server. You can use WEB.SHOW_DOCUMENT to display the report in the browser:

DECLARE
   v_url VARCHAR2(2000);
BEGIN
   v_url := 'http://myserver/reports/sales_report.pdf';
   WEB.SHOW_DOCUMENT(v_url, '_blank');
END;

This opens the report in a new tab, allowing the user to view or download it.

Example: Calling Oracle Reports from Forms

One of the most common uses of WEB.SHOW_DOCUMENT is to integrate with Oracle Reports. For example:

DECLARE
   v_report_url VARCHAR2(2000);
BEGIN
   v_report_url := 'http://myserver:7778/reports/rwservlet?report=sales.rdf&userid=scott/tiger@orcl';
   WEB.SHOW_DOCUMENT(v_report_url, '_blank');
END;

This executes the Sales Report and displays the output in a new browser window.

Example: Opening a Local File

If you have files hosted on a server directory accessible via HTTP:

BEGIN
   WEB.SHOW_DOCUMENT('http://myserver/files/manual.docx', '_blank');
END;

This opens the user manual stored on the server.

Use Cases of WEB.SHOW_DOCUMENT

1. Launching Oracle Reports → Displaying reports in PDF, HTML, or Excel format.
2. Navigating to External Websites → Directing users to company portals or documentation.
3. Opening Uploaded Files → Showing PDFs, images, or documents stored on the server.
4. Integrating with Web Applications → Redirecting to ERP modules, REST services, or dashboards.

Best Practices for WEB.SHOW_DOCUMENT

1. Use Fully Qualified URLs
   Always provide the full HTTP or HTTPS path, especially in web-deployed environments.
2. Choose Target Wisely
   • Use _blank for external websites or large reports.
   • Use _self only when you want to replace the running form session (rarely used).
3. Handle Dynamic URLs
   Construct URLs dynamically using PL/SQL variables when needed. For example, generating report URLs with parameters: DECLARE v_url VARCHAR2(2000); BEGIN v_url := 'http://myserver/reports/rwservlet?report=emp.rdf&P_DEPTNO=' || :EMP.DEPTNO; WEB.SHOW_DOCUMENT(v_url, '_blank'); END;
4. Secure Access
   Ensure sensitive URLs (like reports with credentials) are secured using authentication mechanisms.
5. Test Across Browsers
   Browser behavior may differ when opening documents. Always test on supported environments.

Common Issues and Troubleshooting

• Nothing happens when calling WEB.SHOW_DOCUMENT
  • Check whether the URL is accessible from the client machine.
  • Ensure the browser allows pop-ups (some block new tabs/windows).
• File not found errors
  • Verify that the file path is exposed through HTTP/HTTPS, not just the file system.
• Reports not displaying correctly
  • Make sure the Oracle Reports Server is running and the URL syntax is correct.

Conclusion

The WEB.SHOW_DOCUMENT built-in is an essential tool in Oracle Forms for opening URLs, displaying reports, and integrating with external applications. It provides a clean and user-friendly way to connect your Forms applications with the web. By using proper syntax, handling dynamic URLs, and following best practices, you can significantly enhance your application’s interactivity and usability.