2
Configuring Oracle8i interMedia Web Agent

Before you can use Oracle8i interMedia Clipboard and Web Agent to retrieve, store, and update multimedia data, you must provide information that lets Oracle8i interMedia Clipboard and Web Agent find and access the data. This chapter describes how you configure the Web Agent to provide this information.

For information on configuring your Web server so that it works with the Web Agent, see the following files:

• For Oracle Application Server, wscwrb.html or wscwrb.txt

• For Netscape Web servers, wscns.html or wscns.txt

• For Internet Information Server, wsciis.html or wsciis.txt

• For Apache Web Server, wscapc.html or wscapc.txt

The files are located in the following directory:

• On UNIX and Linux systems: Oracle_home/ord/web

• On Windows NT systems: Oracle_home\Ord\web

2.1 Understanding the Web Agent Configuration

Oracle8i interMedia Web Agent, and indirectly the Clipboard, uses a configuration file, wsc.cfg, to find and access data in a database. The configuration file is located in the following directory on the Web server system:

• On UNIX and Linux systems: Oracle_home/ord/web/admin

• On Windows NT systems: Oracle_home\Ord\admin

The configuration file consists of the following types of sections, each of which contains specific types of information:

• General: Contains general configuration information.

• Web Agent: Contains two sections. One section contains information about the administrative manager of Oracle8i interMedia Web Agent. The other section contains information about Oracle8i interMedia Web Agent.

• Database Agent: Contains sections for each database agent. A database agent specifies information about how the database is accessed, including whether users can retrieve or store information and if they must provide a user name and password. You can have more than one database agent for a database schema.

To modify the configuration file, use the Online Administration form, a Web interface provided with Oracle8i interMedia Web Agent. Using the Online Administration form, you can modify each section of the configuration file, and add and delete database agents.

Note: When you use Apache Web Server, you cannot use the Online Administration form. You edit the configuration file, wsc.cfg.

Section 2.1.1 describes how to use the Online Administration form.

2.1.1 Modifying the Web Agent Configuration

After you install Oracle8i interMedia Web Agent and register it with the Web server, invoke the Online Administration form to modify the configuration of the Web Agent. Invoke the form from your Web browser by using a URL with the following format:

http://domain:port/intermedia/admin

In the format, domain:port represents the domain name and port number of your Web server.

In the login dialog box, enter the following information:

• For User Name, enter the name that is specified in the Web Agent Admin section of the configuration file. By default, the user name is admin.

• For Password, enter the password that is specified in the Web Agent Admin section. By default, the password is manager.

  Note: Oracle recommends that you modify the user name and password to ensure the security of your data.

Oracle8i interMedia Web Agent displays the Online Administration form in the Web browser:

In the left frame, the Online Administration form shows links to sections of the configuration file. In the main frame, it shows the configuration parameters in the general section. In the button frame, the buttons shown, Refresh and Reload in this case, depend on the actions you have taken and the actions available.

To edit the configuration parameters in a section, take these steps:

1. To make sure that you are editing the latest version of the configuration file, click Refresh.

2. From the left frame, click the section you want to edit. The configuration parameters for that section appear in the main frame.

3. Click Edit in the main frame. The Edit screen appears.

   
   

4. Make the changes in the edit boxes, then click Submit.

   When you click Submit, the Online Administration form displays the configuration parameters for the changed entry. However, note that the changes have not yet been written to the current configuration file.

   If you click Reset instead of Submit, the form displays the original values for the section. You can also cancel the edits by clicking on another section in the left frame.

5. After you click Submit, you can click on one of several buttons:
   • Save: Writes the changes to the configuration file. Note, however, that until you click Apply, the Web Agent continues to use the previous version of the configuration file, stored in memory.

   • Undo: Cancels the changes you have made since the last time you saved the file, and loads the current contents of the configuration file into the page.

   • Apply: Writes the changes to the configuration file, loads the changes into the Web server, and restarts the Web Agent.

   • Refresh: Loads the contents of the edit buffer into the page. This button is particularly useful if more than one person is editing the configuration file at a time. It updates the list of database agents, the configuration parameters for each section, as well as the available buttons in the button panel.

   • Reload: Reloads the contents of the configuration file into the page, cancels any changes you have made since the last time you saved the file, and loads the file into the Web server. Reload also restarts the Web Agent.

6. If you are satisfied with the changes, click Apply. The changes are written to the configuration file and loaded into the Web server.

The Online Administration form shows whether a database agent is new, valid, or invalid. In the left pane, new, valid database agents are listed in blue; existing, valid agents are listed in green; invalid agents are listed in red. In addition, when you click a database agent, the main panel lists the Configuration Status as valid or invalid. If it is invalid, check the values of the configuration parameters and check the log file. The Web Agent writes error messages to a log file in the following directory:

• On UNIX and Linux systems: Oracle_home/ord/web/logs

• On Windows NT systems: Oracle_home\Ord\web/logs

The log file may provide clues to the problem. For more information about the log file, see Section 2.3.

To create a new database agent, take these steps:

1. From the left frame, click Database Agents. The configuration parameters for the existing database agents appear in the main frame, along with a Create button.

2. Click Create.

3. Enter the values for the parameters for the new database agent.

   For information about the parameters for database agents, see Section 2.1.5.

4. Click Submit. The database agent name appears in the left frame. By default new, valid database agents are listed in blue, existing, valid agents are listed in green, invalid agents are listed in red.

5. To save the changes to the file and to load the file into the Web server, click Apply.

The following sections describe the different sections of the configuration file and explain the meaning of each configuration parameter.

2.1.2 Specifying General Information

In the general section, you specify the general information about Oracle8i interMedia Web Agent.

Table 2-1 describes the configuration parameters. All parameters are required unless otherwise noted.

Table 2-1  Configuration File: General Section

Parameters	Description
temp_file_dir	The path for the directory to which Oracle8i interMedia Web Agent temporarily stores large objects while you upload them. If the objects are not large, Oracle8i interMedia Web Agent stores them in memory. The default value is the directory defined as the temporary directory for your system. On UNIX and Linux, it is often defined as /tmp. On Windows NT, it is often defined as c:\temp.
iis_extension_url	The virtual path pointing to the file wsciisnn.dll. The path must contain the directory and the name of the file. (The notation nn refers to the release number of the Oracle database client, for example, 81.) This file contains the Microsoft Internet Information Server (IIS) filter and extension. You use the Microsoft Management Console to map the virtual path to the directory. This parameter is required only if you use IIS.

2.1.3 Specifying Administration Information

In the administration section, you specify information that is used for functions relating to the Oracle8i interMedia Web Agent administrative manager. For example, the administrative manager lets you use the Online Administration form to configure the Web Agent.

You specify the information described in Table 2-2. All parameters are required unless otherwise noted.

Table 2-2  Configuration File: Administration Section

Parameters	Description
virtual_path	A virtual path to access the administration Web Agent. The default value is /intermedia/admin.
admin_user	A user name that is used to authenticate clients that request administration functions. The default value is admin.
admin_password	The password used in conjunction with the user name. The default value is manager.

2.1.4 Specifying Oracle8i interMedia Web Agent Information

In the Oracle8i interMedia Web Agent section, you specify information that is used for Oracle8i interMedia Web Agent.

You specify the information described in Table 2-3. All parameters are required unless otherwise noted.

Table 2-3  Configuration File: Oracle8i interMedia Web Agent Section

Parameters	Description
virtual_path	A virtual path that is used as a prefix for all Oracle8i interMedia Web Agent requests. The default value is /intermedia.
image_name	The name of the image for Oracle8i interMedia Web Agent. The image name is wsciwann. (The notation nn refers to the release number of the Oracle database client, for example, 81.) Do not specify the path or the file extension. The file is located in the bin subdirectory of the Oracle_home directory.
entry_point	The entry point of the .dll. The only valid value is wsc_intermedia_web_agent_entry.
agent_list_user	A user name that is used by Oracle8i interMedia Clipboard to access the list of available database agents that have the clipboard request class. The Clipboard prompts you for this user name and password when you connect to Oracle8i interMedia Web Agent. The default value is agents.
agent_list_password	The password used in conjunction with the user name. The default value is list.

2.1.5 Specifying Configuration Information for Database Agents

To access a database through Oracle8i interMedia Clipboard and Web Agent, you create one or more individual database agents by specifying configuration information for each one. The configuration information describes how the database is accessed.

The following example shows the configuration entry for the database agent empdb_read. With this agent, users can retrieve employee pictures from the database. The database_user emp_reader and database_password emp_read_passwrd parameters are used to process the client request in the database.

You can create more than one database agent for each database. For example, you might create one agent that allows users only to retrieve data and another agent that allows users both to retrieve and store data. To use Oracle8i interMedia Clipboard, you must create a database agent with the authorized request class of clipboard.

Table 2-4 describes the configuration parameters in a database agent configuration entry. All parameters are required unless otherwise noted.

Table 2-4  Configuration Entries for Database Agents

Parameters	Description
Agent Name	The name of the particular database agent. You can use any alphanumeric characters and underscores (_) in the name. Because database agent names are used frequently in URLs, do not use other special characters, such as a space, ampersand (&) or plus sign (+). Oracle8i interMedia Clipboard uses this name to construct a URL to retrieve, store, or update data.
service	The SQL*Net service name, which represents the name of the database to which to connect. If you omit this name, the default database is used.
database_user	The user name used to access the database agent. This parameter is optional. If you do not enter the parameter in the configuration file, the Clipboard or browser prompts you for a user name and password when you first use the database agent in a Clipboard or browser session. See Section 2.2 for information on the use of user names and passwords.
database_password	The password used in conjunction with the user name. This parameter is required only if you specify the database_user parameter.
authorized_request_class	The class of requests that can be issued with the specified database agent. The following classes are supported: retrieve: Allows users to retrieve data using a browser, but does not allow them to store or update data in the database nor does it allow them to use Oracle8i interMedia Clipboard. In other words, it allows only mediaget requests to be issued against the database agent. upload: Allows users to retrieve, store, and update data in the database using a browser, but it does not allow them to use Oracle8i interMedia Clipboard. In other words, it allows only mediaget and mediaput requests to be issued against the database agent. clipboard: Allows full access to the database from a browser or Oracle8i interMedia Clipboard. See Section 3.9 for information about mediaget and mediaput request modes.
display_name	A user-specified name that is displayed by Oracle8i interMedia Clipboard. This parameter is optional. If you do not specify it, Oracle8i interMedia Web Agent uses the database agent name.
authentication_realm_name	A user-specified name that is displayed when the browser or Clipboard asks for a user name and password. You can use any alphanumeric characters and underscores (_) in the name. Do not use other special characters, such as an ampersand (&) or plus sign (+). This parameter is optional. If you do not specify it, Oracle8i interMedia Web Agent uses the display name.
retrieve_database_agent	The name of a database agent that allows data retrieval. The configuration file must contain an entry for the named database agent. When the Clipboard generates the URL, it uses this database agent name in the URL. As a result, you can avoid the need to request a user name and password from each browser user. Include this parameter only for those database agents with the authorized_request_class clipboard.
upload_database_agent	The name of a database agent that allows data storage and updating. The configuration file must contain an entry for the named database agent. When the Clipboard generates the URL, it uses this database agent name in the URL. As a result, you can avoid the need to request a user name and password from each browser user. Include this parameter only for those database agents with the authorized_request_class clipboard.
authorized_sql_statements	The type of SQL that can be specified in the URL. The valid types are: procedures: Only names of PL/SQL procedures can be specified to retrieve or store data. any: The names of PL/SQL procedures or the text of SQL statements can be specified to store or retrieve data.
authorized_sql_procedures	A comma-separated list of the PL/SQL procedures that can be executed using this database agent. You can specify one or more procedures, separated by commas. You can also specify an asterisk (*) to indicate that any procedure can be executed. You can express the procedure name in one of the following forms: procedure-name package-name.procedure-name synonym-name.procedure-name schema-name.procedure-name schema-name.package-name.procedure-name The Web Agent evaluates the PL/SQL procedure name in the order listed. This parameter is required only if you use specify procedures as the authorized_sql_statements type.
free_temp_lobs	Whether or not the Web Agent should free temporary LOBs. Include this parameter only if you are using Oracle Application Server. When this parameter is set to TRUE, is blank, or is omitted, the Web Agent frees temporary LOBs. As a result, there is the performance overhead of an extra round-trip to the server. The default, if the parameter is listed, is TRUE. The Online Administration form displays the parameter only if you are using Oracle Application Server. If temporary LOBs are not used by any mediaget requests that use this database agent, set this parameter to FALSE to improve performance.
clipboard_user	The user name used to access the clipboard database agent. It specifies that only the named user can access the database agent. It is valid only for database agents with the authorized_request_class clipboard. This parameter is optional. However, if both clipboard_user and database_user are specified for the database agent, the user names must match.

2.2 Ensuring the Security of Your Data

When you create Web applications, you should consider the security of the data in your database. Oracle8i interMedia Web Agent provides security mechanisms to control which users can access the data, and what operations they can perform on the data. Those mechanisms include:

• User names and passwords

  You can require that users enter a database user name and password to access the data or you can specify the database user name and password in the configuration file.

• Authorized request classes

  When you create a configuration entry for a database agent, you must specify the authorized request classes: retrieve, upload, or clipboard.

• Authorized types of SQL statements

  When you create a configuration entry for a database agent, you must specify the type of SQL that is allowed. You can specify that only PL/SQL procedures are allowed, or you can specify that either PL/SQL procedures or SQL statements are allowed.

  If you specify that only PL/SQL procedures are allowed, you can further restrict access by specifying the names of particular PL/SQL procedures. When you do, no other procedures are allowed to be executed.

You use these security mechanisms by creating database agents in the configuration file. If different types of users have different requirements, create more than one database agent specifying different request classes. Consider creating at least three database agents, one for each authorized request class. To ensure the security of your data, specify the most restrictive class that will still allow users to access the needed data.

The following sections describe how to create database agents for different uses. Section 2.2.4 describes how Oracle8i interMedia Web Agent authenticates users depending on whether or not you specify the user name and password in the configuration file.

2.2.1 Creating a Database Agent for Retrieval

The following example shows a configuration entry for a database agent that specifies the request class retrieve, which lets users retrieve data, but does not let users store or update data.

Because the user name and password are specified in the configuration section for this database agent, when a URL specifies this database agent, users do not need to enter the information to retrieve the data from the database. For more information about specifying the user name and password in the configuration file or requiring users to enter the information, see Section 2.2.4.

To restrict access, only one PL/SQL procedure, GET_EMP_PIC, is authorized for this database agent. As a result, users can retrieve only the data returned by this procedure.

2.2.2 Creating a Database Agent for Storage and Updating

The following example shows a configuration entry for a database agent that specifies the request class upload, which allows users to retrieve, store, and update data. However, because the entry authorizes only two PL/SQL procedures, NEW_EMP_PHOTO and UPDATE_PHOTO, which store and update data, users cannot retrieve data.

Because the user name and password are not specified in the configuration section for this database agent, when a URL specifies this database agent, users must enter the information to store or update the data in the database. For more information about specifying the user name and password in the configuration file or requiring users to enter the information, see Section 2.2.4.

2.2.3 Creating a Database Agent for Clipboard Use

To allow users to retrieve, store, and update data in the database using Oracle8i interMedia Clipboard, as well as using a browser, create a database agent that specifies the request class clipboard.

The following example shows a configuration entry for a database agent that specifies the request class clipboard. Because no user name and password are specified, users must enter this information when they first use the agent during the Clipboard or browser session.

This database agent specifies that the URLs it constructs for retrieval from the database use the database agent empdb_read and the URLs that it constructs for uploading into the database use the database agent empdb_write.

2.2.4 Controlling Access with User Names and Passwords

Oracle8i interMedia Web Agent requires that users provide a user name and password in one of the following ways:

• In the configuration entry for a database agent in Oracle8i interMedia Web Agent configuration file

• From the Web browser or Clipboard

  When you use this method, Oracle8i interMedia Web Agent uses the HTTP Basic Authentication Scheme. The HTTP Basic Authentication Scheme is based on a model where the user agent must authenticate itself with a user ID and a password for each realm. For detailed information about the HTTP Basic Authentication Scheme and how your Web server implements it, see the Web site for the World Wide Web Consortium, http://www.w3.org and your Web server documentation.

The user name specified for a database agent must be a valid database user name and the user must have the appropriate privileges to access the data in the database.

When a user invokes Oracle8i interMedia Clipboard and first connects to Oracle8i interMedia Web Agent, the user must enter the user name and password for the agent list to retrieve the list of database agents that are authorized for clipboard access. The information must match the agent_list_user and agent_list_password in the Web Agent section of the configuration file.

When a user attempts to retrieve or store information in the database, Oracle8i interMedia Web Agent checks the configuration file to see if a user name and password are specified for the database agent. The following explains the resulting actions of Oracle8i interMedia Web Agent:

• If the configuration entry for the database agent contains a user name and password, Oracle8i interMedia Web Agent opens a connection to the database using that user name and password.

  If the user name or password is invalid, the Web Agent writes an error to the error log file.

  If the user name and password are valid, the database server verifies that the user is authorized to perform the requested actions. For example, if the user is attempting to retrieve an image from the database, the specified user name and password must have the SELECT privilege or its equivalent. If the user does not have the required privileges, the image is not returned and the Web Agent writes an error to the error log file.

  If the user is authorized, the request is processed. The database connection and user session remain open. They are available for subsequent requests.

• If the configuration entry for the database agent does not contain a user name and password, Oracle8i interMedia Web Agent uses the HTTP Basic Authentication Scheme to obtain a user name and password from the database user.

  In using this scheme, Oracle8i interMedia Web Agent requests that the browser (or Oracle8i interMedia Clipboard) supply a user name and password. The browser displays a dialog box that prompts the user to enter a user name and password. The dialog box uses the realm name to provide some context to the user about which database agent is being used.

  When the user enters a user name and password, the browser again sends the request, along with the user name and password, to Oracle8i interMedia Web Agent. Oracle8i interMedia Web Agent opens a connection to the database using that user name and password.

  If the user name or password is invalid, Oracle8i interMedia Web Agent again requests that the browser supply a user name and password.

  If the user name and password are valid, the database server verifies that the user is authorized to perform the requested actions. For example, if the user is attempting to retrieve an image from the database, the specified user name and password must have the SELECT privilege or its equivalent. If the user does not have the required privileges, the image is not returned and the Web Agent writes an error to the error log file.

  If the user is authorized, the request is processed. At the same time, the browser associates the user name and password with the realm name and URL. Subsequently, when a request is made using that same URL, the browser sends the user name and password to Oracle8i interMedia Web Agent. This association remains in effect until the user exits the browser. When the request has been processed, the user session ends. The database connection remains open and available for subsequent user sessions and requests.

2.3 Reading Error Messages

Oracle8i interMedia Web Agent writes informational and error messages to the following log file:

• On UNIX and Linux systems: Oracle_home/ord/web/wsc_yyyymmdd_pid.log

• On Windows NT systems: Oracle_home\Ord\web\wsc_yyyymmdd_pid.log

In the format, yyyymmdd signifies the current year, month and day; pid signifies the process ID.

Oracle8i interMedia Web Agent creates a new file when you restart the Web Agent or Web server, provided that the date or process ID has changed.

If the Web Agent encounters circumstances where it cannot write error messages to the specified error log file, such as when a nonrecoverable error occurs during startup, it writes the messages to the wsclstch.err file. On UNIX and Linux, the file is located in the /tmp directory. On Windows NT, the file is located in the %SystemRoot% directory.

See Appendix A for a list of the Web Agent error messages and their meanings.