E
Reports Web Cartridge

E.1 Reports Web Cartridge Example

This section contains step-by-step instructions on how to manually configure the Reports Server using the Web Cartridge on the Oracle Applications Server (OAS). In order to make these configuration procedures meaningful, it is necessary to make several assumptions. For the purposes of this section, the following assumptions are made:

• You are configuring the Reports Server to enable Web requests.

• You are using the Reports Web Cartridge with Oracle Application Server, Release 4.0 or later.

• The Reports Server is installed on a different machine than the Oracle Application Server.

E.1.1 Step 1. Install the software

You must have the Oracle Reports Server software to install and configure the Reports Server. Refer to the Getting Started manual for more information on installing the Oracle Reports Thin Client and Oracle Reports Server components and the Report Builder.

Tip: To install just the Reports Thin Client, Reports Server, or the Report Builder, start the Oracle Installer and choose the Custom Installation options. From the Available Products list box, expand the Oracle Reports Developer node and choose Reports Thin Client, Oracle Reports Server, or Report Builder as desired. Proceed with the installation as described in the Getting Started manual.

On the Web server machine:

1. Install the Oracle Reports Thin Client component after installing your Web server. Refer to your Web server documentation for more information on installing the Web server.

On the Reports Server machine:

1. Install the Oracle Reports Server component and the Report Builder. Note that the Report Builder is required only if you need to build reports. If the Reports Server machine is used only as a deployment machine, then do not install the Report Builder component.

2. When you install the Oracle Reports Server, you will be asked to identify the Reports Server TNS name and Port number. This information is added to the tnsnames.ora file (located in the ORACLE_HOME\NET80\ADMIN directory).
   • Reports Server TNS Name. Type repserver.world or keep the default.

     where repserver.world is the name of the server instance and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance.

   • Port. Type the port number to which the server will listen or keep the default.

   Tip: You can always edit the Reports Server service entry by opening the tnsnames.ora file in a text editor.

3. Make note of the Reports Server TNS name and port number. You will need this information to add the service entry for this Reports Server to the tnsnames.ora file located on the Web server machine. See Section E.1.3.1, "To create a service entry for the Reports Server" for more information.

E.1.2 Step 2. Configure your Web server

This step is performed on your Web server machine.

To configure the Oracle Application Server:

For more information on these steps, refer to your Oracle Application Server documentation.

1. Start the OAS Node Manager.

2. Start your browser.

3. Point your browser to the OAS Node Manager port. Expand the site and HTTP listeners node.

4. Create a listener if necessary, or expand the listener you want to use.

E.1.3 Step 3. Configure the Reports Web Cartridge

This step is performed on your Web server machine.

E.1.3.1 To create a service entry for the Reports Server

If the Web server is on a different machine than your Reports Server, then you must add the Reports Server service entry that was created on the Reports Service machine to the tnsnames.ora file located on your Web server machine. This will enable the Web CGI executable to communicate with the Reports Server.

Tip: If you do not remember the service entry settings for the Reports Server. Open the tnsnames.ora file located in ORACLE_HOME\NET80\ADMIN directory on your Reports Server machine. Copy or make note of the service entry.

1. On your Web Server machine, open the tnsnames.ora file (located in the ORACLE_HOME\NET80\ADMIN directory) in a text editor.

2. Add the following Reports Server service entry:

   repserver.world =(ADDRESS = (PROTOCOL = TCP)(Host = 
   repserver_machine.mydomain)(Port = 1949))
   
   
   

   where:

   repserver.world is the name of the server instance and .world is the domain specified in the NAMES.DEFAULT_DOMAIN setting in the sqlnet.ora file. If the NAMES.DEFAULT_DOMAIN setting is not defined in the sqlnet.ora, then omit .world from the name of the server instance.

E.1.3.2 To set the default Reports Server

For Windows NT

1. On your desktop, choose Start->Run.

2. Type regedit to display the Registry Editor.

3. Expand Hkey_local_machine->Software.

4. Choose Edit->New->String value to add the following environment variable:

   REPORTS60_REPORTS_SERVER=repserver
   
   

   where repserver is the name of the Reports Server that you are configuring (that is, the TNS service entry name of the Reports Server). See Section E.1.1, "Step 1. Install the software".

   Note: Refer to your operating system's documentation to determine if the values you set are case-sensitive.

For UNIX

Tip: You may want to create a shell script that sets environment variables on your Web server machine. To do this, create a file that contains the command described below.

1. Set the REPORTS60_REPORTS_SERVER environment variable to the name of the Reports Server:

   setenv REPORTS60_REPORTS_SERVER repserver
   
   

   where repserver is the name of the Reports Server that you are configuring (that is, the TNS service entry name of the Reports Server). See Section E.1.1, "Step 1. Install the software".

   Tip: Refer to your operating system's documentation to determine if the values you set are case-sensitive.

E.1.3.3 To configure the Reports Web Cartridge (on Windows NT and UNIX)

The steps that follow assume that you have already configured Oracle Application Server, Release 4.0 or later. For more information, refer to your Oracle Application Server documentation.

1. In the Oracle Application Server Welcome page, click OAS Manager.

2. In the OAS Manager navigational tree, click the + icon beside the web site icon.

3. Click the Applications icon.

4. Click the Add icon to display the Add Application form.

5. In the Add Application form, Application Type field, specify C Web.

6. Click Apply.

7. In the Add form, Application Name field, specify the name of your application (for example, Reports).

8. In the Display Name field, specify the display name (for example, Oracle Reports).

9. In the Application Version field, specify a version number (for example, 6.0).

10. Click Apply.

11. In the Success dialog, click Add Cartridge to this Application.

12. In the Add C Web Cartridge form, Cartridge Name field, type: Reports60Cartridge.

13. In the Display Name field, type: Reports60Cartridge.

14. In the Cartridge Shared Object field, specify the location of the shared object file (rwows60.dll). For example, type: D:\ORACLE_HOME\BIN\RWOWS60.DLL.

15. In the Entry Point (Shared Object) field, type: rwows_start.

16. In the Virtual Path field, type: /rwows.

17. Click Apply.

18. In the Success dialog box, click OK.

19. Within the Cartridge Configuration folder, click Tuning.

20. In the Maximum Number of Instances field, type: 100.

21. Click Apply.

22. In the Success dialog box, click OK.

E.1.4 Step 4. Configure the Reports Server

You can configure the Reports Server on Windows NT as a service or a non-service, or you can configure the Reports Server on UNIX. To configure the Reports Server, you need to create a TNS service name in the tnsname.ora file, set environment variables, and then install the Reports Server.

RWMTS60 is the executable for the Reports Server. It has three commands associated with it:

• Install, enables you to install the Reports Server as a service on Windows NT. See Section E.1.4.2.2, "Install the Reports Server on Windows NT as a service" for Windows NT. For UNIX, see Section E.1.4.3, "To configure the Reports Server on UNIX".

• Listen, enables you to install the Reports Server on Windows NT as a non-service. See Section E.1.4.2.3, "Configure the Reports Server on Windows NT as a non-service".

• Uninstall, enables you to uninstall the Reports Server on Windows NT as a service. See Section E.1.4.2.4, "Uninstall the Reports Server on Windows NT".

For Windows NT, you can install, listen, and uninstall the Reports Server manually or in batch mode. Set the BATCH argument to Yes to ignore any error messages raised during the installation and allow the operation to complete without interruption. Any errors or status information raised during installation can be viewed in the Reports Server log file (located on ORACLE_HOME\REPORT60\SERVER\repserver.log). The default for BATCH is No.

This step is performed on the Reports Server machine.

E.1.4.1 To configure the Reports Server on Windows NT

E.1.4.1.1 (Optional) Set the source path

Alternatively, after the Reports Server is installed, you can set the source path in the Reports Server configuration file. See the SOURCEDIR parameter in Appendix B, "Reports Server Configuration Parameters" for more information.

1. Create the source directory if it does not already exist.

2. On your desktop, choose Start->Run.

3. Type regedit to display the Registry Editor.

4. Expand Hkey_local_machine->Software.

5. Double-click REPORTS60_PATH.

6. Add a new reports source path (for example, C:\WEB_REPORTS).

   Note: Refer to your operating system's documentation to determine if the values you set are case-sensitive.

E.1.4.2 To configure the Reports Server on Windows NT

E.1.4.2.1 (Optional) Set the source path

Alternatively, after the Reports Server is installed, you can set the source path in the Reports Server configuration file. See the SOURCEDIR parameter in Appendix B, "Reports Server Configuration Parameters" for more information.

1. Create the source directory if it does not already exist.

2. On your desktop, choose Start->Run.

3. Type regedit to display the Registry Editor.

4. Expand Hkey_local_machine->Software.

5. Double-click REPORTS60_PATH.

6. Add a new reports source path (for example, C:\WEB_REPORTS).

   Note: Refer to your operating system's documentation to determine if the values you set are case-sensitive.

E.1.4.2.2 Install the Reports Server on Windows NT as a service

1. On the Reports Server machine desktop, choose Start->Run.

2. Type the following command line argument:

    rwmts60 -install repserver tcpip
   
   

   or for batch mode:

   rwmts60 -install repserver batch=yes
   
   

   Tip: Repserver does not need to have the domain qualifier appended to it (for example, .world).

3. Click Yes to install the Reports Server as an NT Service and Click OK to start up the service.

4. On your desktop, choose Start->Settings->Control Panel and double-click (Services).

5. In the Services dialog box, choose Oracle Reports Server [repserver] and click Startup.

6. From the startup dialog, select This Account in the Log On As section and type or select an operating system user name and password. This specifies that the server is run as that user.

   Tip: If you want to output to PostScript or to a printer, then ensure the user running the Reports Server service has access to a default printer. Typically, the System Account does not usually have access to printers.

7. Set the service to start automatically (when the system is started).

8. Click OK.

9. Click Start. A Service Control message box indicates when your Reports Server has started. If your Reports Server cannot start, see Appendix F, "Troubleshooting" for more information.

   Tip: When you start the Reports Server for the first time, a Reports Server configuration file (for example, repserver.ora) is created in the ORACLE_HOME\REPORT60\SERVER directory. The setting for your Reports Server cache is set by default. You can change the cache directory, or set the report's source path by modifying the configuration file. If you modify the configuration file, stop and restart the Reports Server for the changes to take effect.

E.1.4.2.3 Configure the Reports Server on Windows NT as a non-service

1. Run the following command line:

   rwmts60 -listen repserver
   
   

   or in batch mode:

   rwmts60 -listen repserver batch=yes
   
   

   Tip: Repserver does not need to have the domain qualifier (for example, .world) appended to it.

E.1.4.2.4 Uninstall the Reports Server on Windows NT

1. On the Reports Server machine desktop, choose Start->Run.

2. Type the following command line argument:

   rwmts60 -uninstall repserver
   
   

   or in batch mode:

   rwmts60 -uninstall repserver batch=yes
   
   

   Tip: Repserver does not need to have the domain qualifier appended to it (for example, .world).

E.1.4.3 To configure the Reports Server on UNIX

E.1.4.3.1 (Optional) Set environment variables

Tip: You may want to create a shell script that sets the environment variables and launches the RWMTS60 executable. To do this, create a file that contains the commands described below.

1. Create a directory for your source reports (for example, /WEB_REPORTS).

2. Set the REPORTS60_PATH environment variable to locate the reports:

   setenv REPORTS60_PATH $WEB_REPORTS
   
   

   Tip: Alternatively, after the Reports Server is installed, you can set the source path in the Reports Server configuration file. See the SOURCEDIR parameter in Appendix B, "Reports Server Configuration Parameters" for more information.

3. Set the TNS_ADMIN environment variable to point to the location of the tnsnames.ora file:

   setenv TNS_ADMIN $ORACLE_HOME/NET80/ADMIN
   
   

   Tip: Refer to your operating system's documentation to determine if the values you set are case-sensitive.

E.1.4.3.2 Starting the Reports Server

1. From the $ORACLE_HOME/BIN directory, run the following command line to run the Reports Server in the foreground:

   rwmts60 name=repserver
   
   

   or to run the Reports Server in the background:

   rwmts60 name-repserver &
   
   

   To determine if your server is running, go to step 6. If your Reports Server does not start or you get an error message, then refer to Appendix F, "Troubleshooting" for more information.

   Tip: When you start the Reports Server for the first time, a Reports Server configuration file (for example, repserver.ora) is created in the $ORACLE_HOME/REPORT60/SERVER directory. The setting for your Reports Server cache is set by default. If you want to change the cache directory, or if you want set the report's source path, then you can do so by modifying the configuration file. If you modify the configuration file, then you will need to stop and restart the Reports Server to acknowledge the changes.

2. (Optional) From the $ORACLE_HOME/BIN directory, run the following command line to ensure that the Reports Server is running:

   rwrqv60 server=repserver
   
   

   Status columns (that is, NAME, OWNER, DEST, etc.) for this Reports Server are displayed. Currently, though, no status information is available since no jobs are running.

   Tip: To kill the Reports Server, press ctrl-C.

   Tip: If you want to output to PostScript or to a printer, then the printer must be configured in the uiprint.txt file (located in the $ORACLE_HOME/GUICOM6/TK60/ADMIN directory).

E.1.5 Step 5. Run a report request

1. Ensure that the Reports Server is configured properly. In a Web browser make the following request:

   http://your_webserver/rwows60?report=your_report.rdf+ 
   userid=username/password@mydb+desformat=html+destype=cache
   
   

   Notice that the SERVER command line argument is missing from the request. It is not required if you set the REPORTS60_REPORTS_SERVER environment variable on your Web Server machine to the repserver.

   Tip: If the report does not run or if you receive an error message, then refer to Appendix F, "Troubleshooting" for more information.

This completes the Reports Server configuration example for a Web Cartridge configuration. You have successfully configured the Reports Server for dynamic reporting using the Reports Web Cartridge.

Next steps:

• (Optional) Tune the Reports Server to optimize performance or implement additional features, such as access control. See Section E.1.6, "Step 6. (Optional) Modify the configuration".

• Make reports available to users. See Chapter 4, "Running Report Requests" for more information on how to specify run requests and make them available to users.

E.1.6 Step 6. (Optional) Modify the configuration

This Reports Server is configured to perform using a default configuration. At some point, you may want to modify the configuration to tune performance, set up monitoring controls, or implement additional features.

• To update the database with job queue information, see Section E.1.6.1, "To update the database with job queue activity".

• To control user access to reports, see Chapter 5, "Controlling User Access to Reports".

• To configure the Reports Server for loading balancing, see Chapter 6, "Configuring Reports Server Clusters".

• To modify a report at runtime based on the audience, see Chapter 7, "Customizing Reports at Runtime".

• To modify the Reports Server configuration file, see Appendix B, "Reports Server Configuration Parameters" for more information about the available configuration parameters.

• Modify environment variables, see Section E.2, "Environment Variables".

E.1.6.1 To update the database with job queue activity

You can set up your database to take snapshots of the Reports Server queue activity whenever jobs are run. When you start the Reports Server, a connection to the database is made. By default, the Reports Server calls an API to delete queue information when the server restarts and to update the queue information in the database table.

You can edit the source for the API in the rw_server.sql script to override the defaults (for example, prevent the queue from being deleted when restarting the Reports Server). The prototype of the procedure (that is, the procedure name and the parameters it expects) should not be edited.

To connect to the database, you set the REPOSITORYCONN parameter in the configuration file. To create the queue activity table in the database, you run the rw_server.sql script.

On the Reports Server machine:

1. Open the repserver.ora configuration file (located on the ORACLE_HOME\REPORT60\SERVER directory) in a text editor.

2. Add the following configuration parameter:

   REPOSITORYCONN="repserver_schema/password@my_db"
   
   

   where repserver_schema/password@database is the connection string to the schema in your database that takes snapshots of queue activity of the specified Reports Server. In this case, repserver_schema is the schema for repserver queue activity.

   Tip: If you want to take snapshots of queue activity from many Reports Servers, then it is recommended that you create a different schema in your database for each Reports Server that you want to take snapshots of. This will prevent you from losing queue activity data when you restart a Reports Server.

3. Run the rw_server.sql script (located in the ORACLE_HOME\REPORT60\SQL directory) from the command line. At the command line prompt, type:

   cd C:\ORACLE_HOME\REPORT60\SQL <RETURN>
   plus80 username/password@my_db <RETURN>
   @rw_server.sql <RETURN>
   quit <RETURN>
   
   

4. Stop and restart the Reports Server to accept the changes made to the configuration file. When the Reports Server starts up, it connects to the database.

   Note: When you restart your Reports Server, queue activity in the database is deleted by default. You can override the default by editing the API.

E.2 Environment Variables

Environment variables are the configuration parameters used to control or customize the behavior of the Reports Server. For Windows NT, environment variables are set using the Registry Editor. For UNIX, variables can be set using a shell script.

Table E-1 Web Cartridge environment variables

Variable	Description
REPORTS60_COOKIE_EXPIRE	Determines the expire time of the cookie in minutes. Default value=30 Cookies save encrypted usernames and passwords on the client-side when users log on to a secured Reports Server to run report requests. When users successfully log on, their browser is sent an encrypted cookie. When a cookie expires, subsequent requests (that is, ones that are sent to secured Reports Servers), user must re-authenticate to run the report.
REPORTS60_DB_AUTH	Specifies the database authentication template used to log on to the database. Default value=dbauth.htm
REPORTS60_ENCRYPTION_KEY	Specifies the encryption key used to encrypt the user name and password for the cookie. The encryption key can be any character string. Default value= reports6.0
REPORTS60_OWSDIAGBODYTAGS	For the Reports Web Cartridge, specifies HTML tags that will be inserted as a <BODY...> tag in the RWOWS diagnostic/debugging output. For example, you may want to use this environment to set up text/background color or image.
REPORTS60_OWSDIAGHEADTAGS	For the Reports Web Cartridge, specifies HTML tags to insert between <HEAD> ...</HEAD> tags in the RWOWS diagnostic/debugging output. For example, you may want to use this environment to set up <TITLE> or <META...> tags.
REPORTS60_OWSHELP	For the Reports Web Cartridge, defines URL/URI of the RWOWS help file, which will be navigated to when RWOWS is invoked with the empty request: http://your_webserver/rwows?. For example, setting it to http://www.yahoo.com will go to that URL; setting it to myhelpfile.htm will display the file: http://your_webserver/myhelpfile.htm. If this parameter is not defined, a default help screen will be displayed.
REPORTS60_OWSMAP	For the Reports Web Cartridge, defines fully qualified filename/location of the RWOWS map file if a map file is used, (for example, C:\ORANT\REPORT60\OWSCMD.DAT).
REPORTS60_OWSNODIAG	For the Reports Web Cartridge, when defined, disables all debugging/diagnostic output, such as help and showmap, from RWOWS. For example, http://your_webserver/rwows/help? will not work when REPORTS60_OWSNODIAG is defined.
REPORTS60_REPORTS_SERVER	Specifies the default Reports Server for Web Cartridge requests. When this parameter is set, you can omit the SERVER command line argument in report requests to process them using the default server, or you can include the SERVER command line argument to override the default.
REPORTS60_SSLPORT	If you are using SSL and you want to use a port number other than 443, you can use this variable to set a different port number. Default value= 443
REPORTS60_SYS_AUTH	Specifies the authentication template used to authenticate the username and password when users run report request to a secured Reports Server. Default value=sysauth.htm