F
Migrating from Web Cartridge to CGI

This appendix contains step-by-step instructions on how to migrate from the Web cartridge to a CGI. For the purposes of this appendix, it is assumed that you have an existing Oracle Reports Services server that is configured on the Oracle Application Server (OAS) using the Web Cartridge.

Note: If you configured the Oracle Reports Services server using the Oracle Portal Listener, any CGI-enabled Web server, or any Java-aware servlet, then you have already configured the Oracle Reports Services server CGI. Migration is not necessary.

F.1 Benefits of Migrating to CGI

CGI is a component of the Web HTTP protocol. It is a standard, platform-independent way to dynamically communicate with the Oracle Reports Services server. Benefits include the following:

• Openness

  Most Web servers support CGI. It is the most common implementation.

• Easy implementation

  CGI is faster and easier to implement than the Web Cartridge.

F.2 Steps for Migrating to CGI

Migrating to CGI involves the following steps:

1. Installing the software.

2. Configuring OAS

3. Configuring the CGI

4. Setting environment variables (optional)

5. Renaming the map files (optional)

6. Running a report using the CGI URL

7. Updating the report links on your Web pages

These steps are performed on your OAS machine and assume that you have an existing Oracle Reports Services server using the Web Cartridge.

F.2.1 Step 1. Installing the Software

You need to do the following to install the software:

1. Install the Oracle Reports Services Developer Thin Client, if you have not already done so.

2. Ensure that a TNSnames service entry exists for the Oracle Reports Services in the tnsnames.ora file that is used by the CGI to communicate with the Oracle Reports Services server.
   • If OAS is installed on a different machine than the Oracle Reports Services, then check the tnsnames.ora file to ensure that a TNSnames service entry exists for the Oracle Reports Services server in the OAS ORACLE_HOME.

   • If OAS release 4.0.8 is installed on the same machine as the Oracle Reports Services, but in a different Oracle home, then you will need to add a TNSnames service entry for the Oracle Reports Services server in the tnsnames.ora file in the OAS ORACLE_HOME.

   • If OAS release 4.0 (previous to OAS 4.0.8) is installed on the same machine as the Oracle Reports Services and is in the same ORACLE_HOME, then no additional TNSnames entries are required.

F.2.2 Step 2. Configuring OAS

To configure OAS, you do the following:

1. Start your browser

2. Click OAS Manager in the Oracle Application Server Welcome page.

3. Click the + icon beside the Web home site icon in the OAS Manager navigational tree.

4. Expand the HTTP listener node.

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

6. Click Directory and configure the OAS directory mapping using the information in the following table.

   Directory Description	Physical Directory Example	Virtual Directory Example	Permissions Required
   BIN	C:\OAS\BIN	/CGI-BIN	read and execute

F.2.3 Step 3. Configuring the CGI

To configure the CGI, you do the following:

1. On Windows, copy the rwcgi60.exe file (located in the ORACLE_HOME\BIN directory) to your CGI-BIN directory. On UNIX, copy the rwcgi60 file (located in the ORACLE_HOME\BIN directory) to your CGI-BIN directory. The CGI-BIN directory is defined in the OAS directory mapping. In this example it is C:\OAS\BIN.

2. If OAS and Oracle Reports Services are in different home directories, then you also need to copy the Oracle Reports Services home into the OAS home.

   On Windows, if the Oracle Reports Services home is D:\ORANT\REPORTS60 and the OAS home is E:\ORANT\OAS, then you need to create a REPORTS60 subdirectory in E:\ORANT\OAS and move the template files from D:\ORANT\REPORTS60 to E:\ORANT\OAS\REPORTS60.

   On UNIX, if the Oracle Reports Services home is /private1/oracle6i/reports60 and OAS is /private1/oas, then you would run the following commands:

   cd/private1/oas
   mkdir reports60
   cd reports60
   cp /private1/oracle6i/reports60/dbauth.htm
   cp /private1/oracle6i/reports60/sysauth.htm
   cp /private1/oracle6i/reports60/dbsysdif.htm
   cp /private1/oracle6i/reports60/dvsyssam.htm
   

F.2.4 Step 4. Setting Environment Variables (Optional)

If you set any Web cartridge environment variables (for example, REPORTS60_OWSHELP to specify the location of the map or help file), then you need to set environment variables for CGI (for example, REPORTS60_CGIHELP).

To display the Web Cartridge environment variables that are currently in use, start your browser and type your OAS Cartridge URL with the snow environment variables command. For example, enter the following:

http://my_webserver/rwows?showenv

F.2.4.1 Windows NT

Before you begin, Oracle Corporation recommends that you back up the registry before making any changes. Do the following steps:

1. Choose StartStart->Run on your desktop.

2. Type regedit to display the Registry Editor.

3. Expand Hkey_local_machine->Software->Oracle.

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

Refer to your operating system's documentation for more information.

F.2.4.2 UNIX

You might want to create a shell script that sets environment variables on your OAS machine. To do this, you create a file that contains the following command for each environment variable that you want set. For example:

setenv REPORTS60_CGIHELP myhelp.html

F.2.5 Step 5. Renaming the Map Files (Optional)

If you use a key mapping file to simplify or hide parameters, then you will need to rename the key mapping file (for example, owscmd.dat) that was for the Web cartridge to file name that CGI can recognize (for example, cgicmd.dat). You can copy and rename the owscmd.dat file (located in ORACLE_HOME\REPORTS60) to cgicmd.dat.

This completes the migration from Web cartridge to CGI.

F.2.6 Step 6. Running a Report Using the CGI URL

You need to test that you have successfully migrated to CGI. You can test the configuration so ensure that it can communicate with the Oracle Reports Services server. The URL for CGI is different than the URL for the Web cartridge. Run a test using the following CGI URL. For this example, it is assumed that the REPORTS60_REPORT_SERVER environment variable was set to point to a default Oracle Reports Services server. The SERVER command line argument is not needed in this case.

http://your_webserver/CGI-BIN/RWCGI60.EXE?REPORT=your_report.RDF+userid=username/password@
mydb+DESFORMAT=HTML+DESTYPE=CACHE

Notice that instead of using the RWOWS60 executable (for Web Cartridge) you are calling the RWCGI60 executable (for CGI) from the CGI-BIN path (that was defined in Step 2) to call the URL. The arguments that follow the ? (question mark) are the same, regardless of whether you are using Web cartridge or CGI to communicate with the Oracle Reports Services server.

F.2.7 Updating the Report Links on Your Web Page

If you maintain a Web page with links to run report requests, then you will need to change the URL reference to call the RWCGI60 executable from the CGI-BIN path.

If you configured your Oracle Reports Services server for access control using Oracle Portal, then you will need to change the Web gateway value in the Oracle Reports Services server access control, which was created for the Oracle Reports Services server.