Oracle8i interMedia
Using Oracle8i interMedia with the Web
Release 8.1.5.2

A77033-01

Contents

Index

Prev Next

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:

The files are located in the following directory:

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:

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

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:

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:

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:

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:

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:

2.3 Reading Error Messages

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

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.


Prev Next
Oracle
Copyright © 1999 Oracle Corporation.
All Rights Reserved.

Contents

Index