17.13 Using a Key Map File

17.13.1 Understanding Key Mapping

The key map file contains command strings for running reports, each headed by a unique key identifier. Except when you run a report as a JSP, you reference only this key in the runtime URL. Oracle Reports Servlet (rwservlet) sends the key value to the key map file (cgicmd.dat), which in turn returns the command associated with the specified key to rwservlet for processing. By using key mapping, the command line options are all hidden from the user.

Key mapping is useful for:

• Shortening the URL, making it more convenient to use.

• Remapping the runtime commands without having to change the original URL.

• Standardizing several typical run configurations for your company.

• Hiding certain parameters from users (for example, the database connect string).

• Restricting the parameters users can use to run a report.

When you specify a key name from the key map file (cgicmd.dat), it must always be at the beginning of the query string (after the question mark) in a report request URL. An exception to this is if you use the CMDKEY command line keyword, and express the key name as its value: CMDKEY=keyname. In this case, you can place the key name anywhere in the query string within the report request URL. The CMDKEY keyword can be used with jobs run as JSPs and with the rwservlet command.

17.13.2 Enabling Key Mapping

Key mapping is enabled when a valid file with the standard file name, cgicmd.dat, is present in the default location: $DOMAIN_HOME/servers/WLS_REPORTS/stage/reports/reports/configuration/cgicmd.dat directory on the Web server machine (on either Windows or UNIX).

17.13.3 Adding Key Mapping Entries to a Key Map File

To add key mapping entries to a key map file:

1. Navigate to the cgicmd.dat file on the machine that hosts your Reports Server, and open it with a text editor.

   You'll find this file in the following directory on both Windows and UNIX:

   $DOMAIN_HOME/servers/WLS_REPORTS/stage/reports/reports/configuration/cgicmd.dat
   

2. Add a key mapping entry. For example:

   key1: report=your_report.rdf userid=username/password@my_db desformat=html SERVER=server_name destype=cache
   

   In this example, key1 is the name of the key.

   Except for the special parameters that are described in the file itself, the command line options follow the syntax rules of rwclient. See Section A.2.1, "rwclient" for more information.

3. Add or update the hyperlinks on your Web page.

   For more information, see Section 17.5, "Specifying a Report Request from a Web Browser".

17.13.4 Using a Key with Non-JSP Reports

When you place a key name in a report request URL, it must always be the first value within the query string (immediately after the question mark). For example:

http://…/rwservlet?keyname

The key name is case-sensitive; that is, it must exactly match the case specified in the key mapping file (cgicmd.dat).

The following example shows a key mapping for a restricted run with a parameter form.

The URL might be:

http://web_server.domain_name:port/reports/rwservlet?run_report&par1&par2&parN

The key mapping file (cgicmd.dat) might contain:

run_report: report=myreport deptno=%1 myparam=%2 %* 

This generates the equivalent of the following command line request:

rwclient report=myreport deptno=par1 myparam=par2 parN

17.13.5 Using a Key with a Report Run as a JSP

When you run a report as a JSP and want to call a command key in the cgicmd.dat file, you must use the cmdkey keyword in your URL. The cmdkey value (keyname) is case-sensitive; that is, it must exactly match the case specified in the cgicmd.dat file. For example, your JSP URL might look like this:

http://…/myreport.jsp?cmdkey=keyname

When you use cmdkey with a JSP or rwservlet, you can place it anywhere within the query string. For example:

http://…/example.jsp?parameter1=value1&cmdkey=keyname
http://…/rwservlet?parameter1=value1&cmdkey=keyname

Usage Note

When using key mapping, the order in which the parameters are substituted from the URL into the key is determined by the placement of cmdkey in the URL. For example, suppose you have a key such as the following in the cgicmd.dat file:

mykeys: DEPTNO=%1 MYPARAM=%2

Now, you execute a JSP report that references this key as follows:

http://neptune.world.com:80/jsp/myreport.jsp?userid=scott/tiger@hrdb
  &cmdkey=mykeys&10&test

Because of the placement of cmdkey in this URL, the 10 corresponds to %1 and test corresponds to %2. Even though they are not the first and second parameters in the URL, 10 and test are the first and second parameters to follow cmdkey in the URL. In this example, the URL becomes:

http://neptune.world.com:80/jsp/myreport.jsp?userid=scott/tiger@hrdb
  &DEPTNO=10&MYPARAM=test