Skip Headers

Oracle® HTML DB User's Guide
Release 1.5

Part Number B10992-01
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page
Previous
Go to next page
Next
View PDF

12 Advanced Programming Techniques

This section provides information about advanced programming techniques including establishing database links, using collections, running background SQL, utilizing Web Services and managing user preferences.

This section contains the following topics:

Accessing Data with Database Links

Since Oracle HTML DB runs on top of an Oracle database, you have access to all distributed database capabilities. Typically, you perform distributed database operations using database links.

To use database links, you must create a standard database link using the following standard Oracle syntax:

CREATE DATABASE LINK linkname
CONNECT TO username IDENTIFIED BY password 
USING 'tns_connect_string';

The tns_connect_string entry on your local server should correspond to the information in your SERVERS tnsnames.ora file. It is a good idea to name your database link the global name of the remote database.

Using Collections

Collections enable you to temporarily capture one or more non-scalar values. You can use collections to store rows and columns currently in session state so they can be accessed, manipulated, or processed during a user's specific session. Think of a collection as a bucket in which you can temporarily store and name rows of information.

Examples of when you might use collections include:

Using the HTMLDB_COLLECTION API

You implement a collection using the PL/SQL API HTMLDB_COLLECTION. Using this API you can insert, update, and delete collection information.

Topics in this section include:

About Collection Naming

When you create a new collection, you must give it a name that cannot exceed 255 characters. Note that collection names are not case sensitive and will be converted to upper case.

Once named, you can access the values in a collection by running a SQL query against the view HTMLDB_COLLECTION.

Creating a Collection

Every collection contains a named list of data elements (or members) which can have up to 50 attributes (or columns). Use the following methods to create a collection:

  • CREATE_COLLECTION

  • CREATE_OR_TRUNCATE_COLLECTION

  • CREATE_COLLECTION_FROM_QUERY

CREATE_COLLECTION raises an exception if the named collection already exists. For example:

HTMLDB_COLLECTION.CREATE_COLLECTION(
    p_collection_name => collection name );

CREATE_OR_TRUNCATE_COLLECTION creates a new collection if the named collection does not exist. If the named collection already exists, this method truncates it. Truncating a collection empties it, but leaves it in place. For example:

HTMLDB_COLLECTION.CREATE_OR_TRUNCATE_COLLECTION(
    p_collection_name => collection name );

CREATE_COLLECTION_FROM_QUERY creates a collection then populates it with the results of a specified query. For example:

HTMLDB_COLLECTION.CREATE_COLLECTION_FROM_QUERY(
    p_collection_name => collection name,
    p_query           => your query );

Truncating a Collection

Truncating a collection removes all members from the specified collection, but leaves the named collection in place. For example:

HTMLDB_COLLECTION.TRUNCATE_COLLECTION(
    p_collection_name => collection name );

Deleting a Collection

Deleting a collection deletes the collection and all of its members. Be aware that if you do not delete a collection, it will eventually be deleted when the session is purged. For example:

HTMLDB_COLLECTION.DELETE_COLLECTION (
    p_collection_name => collection name );

Deleting All Collections for the Current Application

Use the method DELETE_ALL_COLLECTIONS to delete all collections defined in the current application. For example:

HTMLDB_COLLECTION.DELETE_ALL_COLLECTIONS;

Deleting All Collections in the Current Session

Use the method DELETE_ALL_COLLECTIONS_SESSION to delete all collections defined in the current session. For example:

HTMLDB_COLLECTION.DELETE_ALL_COLLECTIONS_SESSION;

Adding Members to a Collection

When data elements (or members) are added to a collection, they are assigned a unique sequence ID. As you add members to a collection, the sequence ID will change in increments of 1 with the newest members having the largest ID.

You add new member to a collection using the function ADD_MEMBER. Calling this method returns the sequence ID of the newly added member. The following example demonstrates how to use the procedure ADD_MEMBER.

HTMLDB_COLLECTION.ADD_MEMBER(
    p_collection_name => collection name,
    p_c001          => [member attribute 1],
    p_c002          => [member attribute 2],
    p_c003          => [member attribute 3],
    p_c004          => [member attribute 4],
    p_c005          => [member attribute 5],
    p_c006          => [member attribute 6],
    p_c007          => [member attribute 7],
  ...
    p_c050          => [member attribute 50]);

The next example demonstrates how to use the function ADD_MEMBER. This function returns the sequence number assigned to the newly created member.

l_id := HTMLDB_COLLECTION.ADD_MEMBER(
    p_collection_name => collection name,
    p_c001          => [member attribute 1],
    p_c002          => [member attribute 2],
    p_c003          => [member attribute 3],
    p_c004          => [member attribute 4],
    p_c005          => [member attribute 5],
    p_c006          => [member attribute 6],
    p_c007          => [member attribute 7],
  ...
    p_c050          => [member attribute 50]);


You can also add new members (or an array of members) to a collection using the method ADD_MEMBERS. This method raises an exception if the specified collection does not exist with the specified name of the current user and in the same session. Also any attribute exceeding 4,000 characters will be truncated to 4,000 characters. The number of members added is based on the number of elements in the first array. For example:

HTMLDB_COLLECTION.ADD_MEMBERS(
    p_collection_name => collection name,
    p_c001          => member attribute array 1,
    p_c002          => member attribute array 2,
    p_c003          => member attribute array 3,
    p_c004          => member attribute array 4,
    p_c005          => member attribute array 5,
    p_c006          => member attribute array 6,
    p_c007          => member attribute array 7,
    ...
    p_c050          => member attribute array 50);

Updating Collection Members

You can update collection members by calling UPDATE_MEMBER and referencing the desired collection member by its sequence ID. This procedure replaces an entire collection member, not individual member attributes. This procedure raises an exception if the named collection does not exist. For example:

HTMLDB_COLLECTION.UPDATE_MEMBER (
    p_collection_name => collection name,
    p_seq             => member sequence number,
    p_c001            => member attribute 1,
    p_c002            => member attribute 2,
    p_c003            => member attribute 3,
    p_c004            => member attribute 4,
    p_c005            => member attribute 5,
    p_c006            => member attribute 6,
    p_c007            => member attribute 7,
    ...
    p_c050            => member attribute 50);

If you wish to update a single attribute of a collection member, use UPDATE_MEMBER_ATTRIBUTE. Calling this procedure raises an exception if the named collection does not exist. For example:

HTMLDB_COLLECTION.UPDATE_MEMBER_ATTRIBUTE(
    p_collection_name => collection name,
    p_seq             => member sequence number,
    p_attr_number     => number of attribute to be updated,
    p_attr_value      => new attribute value);

Deleting a Collection Member

You can delete a collection member by calling DELETE_MEMBER and referencing the desired collection member by its sequence ID. For example:

HTMLDB_COLLECTION.DELETE_MEMBER(
    p_collection_name => collection name,
    p_seq             => member sequence number);

Be aware that this procedure leaves a gap in the sequence IDs in the specified collection. Also, calling this procedure results in an error if the named collection does not exist.

You can also delete all members from a collection by when an attribute matches a specific value. For example:

HTMLDB_COLLECTION.DELETE_MEMBERS(
    p_collection_name => collection name,
    p_attr_number     => number of attribute to be updated,
    p_attr_value      => new attribute value);

Be aware that this procedure also leaves a gap in the sequence IDs in the specified collection. Also, this procedure raises an exception if:

  • The named collection does not exist

  • The specified attribute number is outside the range of 1 to 50, or is in invalid

If the supplied attribute value is null, then all members of the named collection will deleted.

Determining Collection Status

Each collection contains a flag to determine if the contents of the collection has changed. This flag is set when you first create a collection by calling CREATE_COLLECTION or CREATE_OR_TRUNCATE_COLLECTION. You can reset this flag manually by calling RESET_COLLECTION_CHANGED. For example:

HTMLDB_COLLECTION.RESET_COLLECTION_CHANGED (
    p_collection_name => collection name)

Once this flag has been reset, you can determine if a collection has changed by calling COLLECTION_HAS_CHANGED. For example:

l_changed := HTMLDB_COLLECTION.COLLECTION_HAS_CHANGED(
  p_collection_name => collection_name);

When you add a new member to a collection, an MD5 message is automatically computed against all 50 attributes of the member. You can access this value from the MD5_ORIGINAL column of the view HTMLDB_COLLECTION using the function GET_MEMBER_MD5. For example:

HTMLDB_COLLECTION.GET_MEMBER_MD5 (
    p_collection_name => collection name,
    p_seq             => member sequence number );
    RETURN VARCHAR2;

Merging Collections

You can merge members of collection with values passed in a set of arrays. By using the argument p_init_query, you can create a collection from the supplied query. Be aware, however, that if the collection exists, the following occurs:

  • Rows in the collection (not in the arrays) will be deleted

  • Rows in the collection and in the arrays will be updated

  • Rows in the array and not in the collection will be inserted

Any attribute value exceeding 4,000 characters will be truncated to 4,000 characters. Table 12-1 describes the available arguments you can use when merging collections.

Table 12-1 Available Arguments for Merging Collections

Argument Description
p_c001 Array of first attribute values to be merged. Maximum length can be 4,000 characters. If the maximum length is greater, it will be truncated to 4,000 characters.

The count of elements in the P_C001 PL/SQL table is used as the total number of items across all PL/SQL tables. For example, if P_C001.count = 2 and P_C002.count = 10, only 2 members will be merged. Be aware that if P_C001 is null, an application error will be raised.

p_c0xx Attribute of XX attributes values to be merged. Maximum length can be 4,000 characters. If the maximum length is greater, it will be truncated to 4,000 characters.
p_collection_name Name of the collection.

See Also: "About Collection Naming"

p_null_index Use this argument to identify rows the merge function should ignore. This argument identifies an row as null. Null rows are automatically removed from the collection. Use p_null_index in conjunction with.
p_null_value Use this argument in conjunction with the p_null_index. Identifies the null value. If used this value cannot be null. A typical value for this argument is 0.
p_init_query Use the query defined by this argument to create a collection if the collection does not exist.

Managing Collections

You can use the following utilities to manage collections.

Obtaining a Member Count

Use COLLECTION_MEMBER_COUNT to return the total count of all members in a collection. Be aware that this count does not imply the highest sequence in the collection. For example:

l_count := HTMLDB_COLLECTION.COLLECTION_MEMBER_COUNT (
  p_collection_name => collection name );
Resequencing a Collection

Use RESEQUENCE_COLLECTION to resequence a collection to remove any gaps in sequence IDs while maintaining the same element order. For example:

HTMLDB_COLLECTION.RESEQUENCE_COLLECTION (
   p_collection_name => collection name )
   
Verifying Whether a Collection Exists

Use COLLECTION_EXISTS to determine if a collection exists. For example:

l_exists := HTMLDB_COLLECTION.COLLECTION_EXISTS  (
  p_collection_name => collection name );
Adjusting Member Sequence ID

You can adjust the sequence ID of a specific member within a collection by moving the ID up or down. When you adjust a sequence ID, the specified ID is exchanged with another one. For example, if you were to move the ID 2 up, 2 would become 3 and 3 would become 2.

Use MOVE_MEMBER_UP to adjust a member sequence ID up by one. Alternately, use MOVE_MEMBER_DOWN to adjust a member sequence ID down by one. For example:

HTMLDB_COLLECTION.MOVE_MEMBER_DOWN(
    p_collection_name => collection name,
    p_seq             => member sequence number);

Be aware that while using either of these methods an application error displays:

  • If the named collection does not exist for the current user in the current session

  • If the member specified by sequence ID p_seq does not exist

However, an application error will not be returned if the specified member already has the highest or lowest sequence ID in the collection (depending on whether you are calling MOVE_MEMBER_UP or MOVE_MEMBER_DOWN).

Sorting Collection Members

Use SORT_MEMBERS to reorder members of a collection by the column number. This method not only sorts the collection by a particular column number, but it also reassigns the sequence IDs for each member to remove gaps. For example:

HTMLDB_COLLECTION.SORT_MEMBERS(
    p_collection_name       => collection name,
    p_sort_on_column_number => column number to sort by);

Clearing Collection Session State

By clearing the session state of a collection, you remove the collection members. A shopping cart is a good example of when you might need to clear collection session state. When a user requests to empty his or her cart and start again, you would need to clear the session state for a collection. You can remove session state of a collection by calling the CREATE_OR_TRUNCATE_COLLECTION method or by using f?p syntax.

Calling CREATE_OR_TRUNCATE_COLLECTION deletes the existing collection and then recreates it. For example:

HTMLDB_COLLECTION.CREATE_OR_TRUNCATE_COLLECTION(
    p_collection_name       => collection name,

You can also use the sixth f?p syntax argument to clear session state. For example:

f?p=App:Page:Session::NO:1,2,3,collection name

Running Background PL/SQL

You can use the HTMLDB_PLSQL_JOB package to run PL/SQL code in the background of your application. This is an effective approach for managing long running operations that do not need to complete in order for a user to continue working with your application.

Topics in this section include:

Understanding the HTMLDB_PLSQL_JOB Package

HTMLDB_PLSQL_JOB is a wrapper package around DBMS_JOB functionality offered in the Oracle database. Be aware that the HTMLDB_PLSQL_JOB package only exposes that functionality which is necessary to run PL/SQL in the background. The following is a description of the HTMLDB_PLSQL_JOB package.

SQL> DESC HTMLDB_PLSQL_JOB
FUNCTION JOBS_ARE_ENABLED RETURNS BOOLEAN
PROCEDURE PURGE_PROCESS
 Argument Name                  Type                    In/Out Default?
 ------------------------------ ----------------------- ------ --------
 P_JOB                          NUMBER                  IN
FUNCTION SUBMIT_PROCESS RETURNS NUMBER
 Argument Name                  Type                    In/Out Default?
 ------------------------------ ----------------------- ------ --------
 P_SQL                          VARCHAR2                IN
 P_WHEN                         VARCHAR2                IN     DEFAULT
 P_STATUS                       VARCHAR2                IN     DEFAULT
FUNCTION TIME_ELAPSED RETURNS NUMBER
 Argument Name                  Type                    In/Out Default?
 ------------------------------ ----------------------- ------ --------
 P_JOB                          NUMBER                  IN
PROCEDURE UPDATE_JOB_STATUS
 Argument Name                  Type                    In/Out Default?
 ------------------------------ ----------------------- ------ --------
 P_JOB                          NUMBER                  IN
 P_STATUS                       VARCHAR2                IN
 P_DESC                         

Table 12-1 describes the functions available in the HTMLDB_PLSQL_JOB package.

Table 12-2 HTMLDB_PLSQL_JOB Package Available Functions

Function Description
SUBMIT_PROCESS Use this procedure to submit background PL/SQL. This procedure returns a unique job number. Since you can use this job number as a reference point for other procedures and functions in this package, it may be useful to store it in your own schema.
UPDATE_JOB_STATUS Call this procedure to update the status of the currently running job. This procedure is most effective when called from the submitted PL/SQL.
TIME_ELAPSED Use this function to determine how much time has elapsed since the job was submitted.
JOBS_ARE_ENABLED Call this function to determine whether or not that database is currently in a mode which supports submitting jobs to the HTMLDB_PLSQL_JOB package.
PURGE_PROCESS Call this procedure to clean up submitted jobs. Submitted jobs stay in the HTMLDB_PLSQL_JOBS view until either Oracle HTML DB cleans out those records, or you call PURGE_PROCESS to manually remove them.

You can view all jobs submitted to the HTMLDB_PLSQL_JOB package using the HTMLDB_PLSQL_JOBS view. The following is the description of HTMLDB_PLSQL_JOBS view.

SQL> DESCRIBE HTMLDB_PLSQL_JOBS
 Name                              Null?    Type
 --------------------------------- -------- ----------------------------
 ID                                         NUMBER
 JOB                                        NUMBER
 FLOW_ID                                    NUMBER
 OWNER                                      VARCHAR2(30)
 ENDUSER                                    VARCHAR2(30)
 CREATED                                    DATE
 MODIFIED                                   DATE
 STATUS                                     VARCHAR2(100)
 SYSTEM_STATUS                              VARCHAR2(4000)
 SYSTEM_MODIFIED                            DATE
 SECURITY_GROUP_ID                          NUMBER

Table 12-3 describes the columns available in HTMLDB_PLSQL_JOBS view.

Table 12-3 HTMLDB_PLSQL_JOBS View Columns

Name Description
ID An unique identifier for each row.
JOB The job number assigned to each submitted PL/SQL job. The HTMLDB_PLSQL_JOB.SUBMIT_PROCESS function returns this value. This is also the value you pass into other procedures and functions in the HTMLDB_PLSQL_JOB package.
FLOW_ID The application from which this job was submitted.
OWNER The database schema that owns the application. This identifies what schema will parse this code when DBMS_JOB runs it.
ENDUSER The end user (that is, who logged into the application) that caused this process to be submitted.
CREATED The date when the job was submitted.
MODIFIED The date when the status was modified.
STATUS The user defined status for this job. Calling HTMLDB_PLSQL_JOB.UPDATE_JOB_STATUS updates this column.
SYSTEM_STATUS The system defined status for this job.
SYSTEM_MODIFIED The date when the system status was modified.
SECURITY_GROUP_ID The unique ID assigned to your workspace. Developers can only see jobs submitted from their own workspace.

About System Status Updates

Submitted jobs can contain any of the following system status settings:

  • SUBMITTED. Indicates the job has been submitted, but has not yet started. DBMS_JOB does not guarantee immediate starting of jobs.

  • IN PROGRESS. Indicates that DBMS_JOB has started the process.

  • COMPLETED. Indicates the job has finished.

  • BROKEN (sqlcode) sqlerrm. Indicates there was a problem in your job that resulted in an exception. The SQL code and SQL Error Message for the exception should be included in the system status. Review this information to determine what went wrong.

Using a Process to Implement Background PL/SQL

The simplest way to implement the HTMLDB_PLSQL_JOB package is to create a page process that specifies the process type PLSQL DBMS JOB. By selecting this process type, Application Builder will submit the PL/SQL code you specify as a job. Since you are not calling the function directly, you can use the built-in substitution item APP_JOB to determine the job number of any jobs you submit.

The following example runs a PL/SQL job in the background for testing and explanation.

001  BEGIN
002    FOR i IN 1 .. 100 LOOP
003      INSERT INTO emp(a,b) VALUES (:APP_JOB,i);
004      IF MOD(i,10) = 0 THEN
005        HTMLDB_PLSQL_JOB.UPDATE_JOB_STATUS(
006          P_JOB     => :APP_JOB,
007          P_STATUS  => i || 'rows inserted');
008      END IF;
009      HTMLDB_UTIL.PAUSE(2);
010    END LOOP;
011  END;

In this example, note that:

  • Lines 002 to 010 run a loop that inserts 100 records into the emp table.

  • APP_JOB is referenced as a bind variable inside the VALUES clause of the INSERT, and specified as the P_JOB parameter value in the call to UPDATE_JOB_STATUS.

  • APP_JOB represents the job number which will be assigned to this process as it is submitted to HTMLDB_PLSQL_JOB. By specifying this reserved item inside your process code, it will be replaced for you at execution time with the actual job number.

  • Notice this example calls to UPDATE_JOB_STATUS every ten records, INSIDE the block of code. Normally, Oracle transaction rules dictate updates made inside code blocks will not be seen until the entire transaction is committed. The HTMLDB_PLSQL_JOB.UPDATE_JOB_STATUS procedure, however, has been implemented in such a way that the update will happen regardless of whether or not the job succeeds or fails. This last point is important for two reasons:

    1. Even if your status reads "100 rows inserted," it does not mean the entire operation was successful. If an exception occurred at the time the block of code tried to commit, the user_status column of HTMLDB_PLSQL_JOBS would not be affected since status updates are committed separately.

    2. These updates are performed autonomously. You can view the job status before the job has completed. This gives you the ability to display status text about ongoing operations in the background as they are happening.

Implementing Web Services

Web services in Oracle HTML DB are based on SOAP (the Simple Object Access Protocol). SOAP is a World Wide Web Consortium (W3C) standard protocol for sending and receiving requests and responses across the Internet. SOAP messages can be sent back and forth between a service provider and a service user in SOAP envelopes. SOAP envelopes contain a request for some action and the result of that action and are formatted in XML.

Because SOAP is based on XML and uses simple transport protocols such as HTTP, SOAP messages are not blocked by firewalls and is very easy to use. A SOAP message consists of the following:

Note that the SOAP 1.1 specification is a W3C note. (The W3C XML Protocol Working Group has been formed to create a standard that will supersede SOAP.)


See Also:

For more information on Simple Object Access Protocol (SOAP) 1.1 see:
http://www.w3.org/TR/SOAP/


Creating a Web Service

To create a Web service in Oracle HTML DB, you must provide:

  • The URL used to post the SOAP request over HTTP

  • An URI (Uniform Resource Identifier) identifying the SOAP HTTP request

  • A Proxy address

  • A SOAP envelope

To create a new Web service:

  1. Click the Build icon.

  2. From the Available Applications list, select an application and click Go.

  3. Select the WebServices tab.

    The Web Services pages appears. Existing services display in the Web Services Repository. You can test an existing service by clicking the service name.

  4. To create a new Web service, click Create.

    The Create/Edit Web Service page appears. Required attributes are identified with a red asterisk (*).

  5. In Web Service Identification, enter a name for this Web service. This name only appears within the context of Application Builder.

  6. Under Service Description, specify the following:

    • In URL, specify the URL used to post the SOAP request over HTTP. This URL corresponds to the soap:address location of a service port in the WSDL (Web Services Description Language). For example:

      http://www.alethea.net/webservices/LocalTime.asmx
      
      
    • In Action, indicate the intent of the SOAP HTTP request. This value is a URI (Uniform Resource Identifier) identifying the intent. SOAP places no restrictions on the format or specificity of the URI or whether or not it is resolvable. An HTTP client must use this header field when issuing a SOAP HTTP Request.

    • In Proxy, enter a proxy using the following syntax:

      http://host:port/
      
      

      This proxy overrides the system defined HTTP proxy for your request and may include an optional TCP/IP port number at which the proxy server listens. For example,

      www-proxy.myworkspace.com
      
      
  7. In SOAP Envelope, specify the SOAP envelope to be used for the SOAP request to the Web service. This envelope can contain item substitutions using the syntax #ITEM_NAME#. For example:

    <SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
      xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
      xmlns:xsd="http://www.w3.org/1999/XMLSchema"
      SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
      <SOAP-ENV:Body><LocalTimeByZipCode 
    xmlns="http://www.alethea.net/webservices/"><ZipCode
    xsi:type="xsd:string">#Fxxxx_Pyyy_ZIP_
    CODE#</ZipCode></LocalTimeByZipCode></SOAP-ENV:Envelope>
    
    
  8. Under Style Sheet Rendering, enter an enter a valid XSL style sheet. This style sheet:

    • Renders the result of the Web Service in a page region.

    • Is used to apply an XML transformation against the result of the SOAP request.

    • Render the output in a Web Service page region.

  9. Click Create.

Invoking a Web Service as a Process

You can also implement a Web Service as a process on the page. Running the process submits the request to the service provider. You can then display the request results in Web Service region and use a style sheet to render the output.

To invoke a Web Service as a process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Page Processes, click Create.

    The Create Page Computation Wizard appears.

  3. Specify a process name, sequence, and processing point.

  4. From Type, select Web Service.

  5. Identify the Web Service.

  6. Follow the on-screen instructions

To create a Web Service region:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Regions, click Create.

    The Create Region Wizard appears.

  3. Select the region type Other and then select Web Service Result.

  4. Follow the on-screen instructions.

Managing User Preferences

You can use preferences to set the session state for a specific user. Once set, these preferences can only be removed by an Oracle HTML DB administrator. You can set user preferences by creating a page process, by the calculation of a preference Item Source Value, or programatically using the PL/SQL API.

Topics in this section include:

Viewing User Preferences

You view user preferences for a specific user on the Session State Management page.

To view user preferences for a specific user:

  1. From the Oracle HTML DB Home page select the Administration tab.

  2. Under Administration Services, click Manage Users and then Session State.

    The Session State Management page appears.

  3. Click Report preferences for users.

  4. Type a username in the field provided and click Go.


See Also:

"Administering Session State and User Preferences" for more information on using the Session State Management page

Setting User Preferences

You can set user preferences within your application through the creation of a page process, by creating a preference item, or programatically.

Topics in this section include:

Setting User Preferences Using a Page Process

To set user preference values by creating a page process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Page Processes, click Create.

    The Create Page Computation Wizard appears.

  3. Specify a process name, sequence, and processing point.

  4. From Type, select one of the following:

    • Set Preference to value of item

    • Set Preference to value of item if item is not NULL

  5. Specify the preference value in the field provided using the format:

    PreferenceName:Item
    
    
  6. Click Page Items to see a list of available items.

  7. Follow the on-screen instructions

Setting the Source of an Item Based on a User Preference

You can set the source of an item based on a user preference by defining the item source type as Preference.

To define the source of item based on a user preference:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Item, click Create.

    The Create Page Computation Wizard appears.

  3. Specify the Item Name and Display Position Attributes and click Next.

  4. Specify the Item Attributes click Next.

  5. From the Item Source list, select Preferences.

  6. In Item Source Value, enter the name of the preference.

  7. Follow the on-screen instructions

Setting User Preferences Programatically

To set or reference user preferences programatically, you must use a PL/SQL API. User level caching is available programmatically. You can use the set_preferences function to set a user level preference called NAMED_PREFERENCE. For example:

HTMLDB_UTIL.SET_PREFERENCE(
 p_preference=>'NAMED_PREFERENCE',
 p_value     =>v('ITEM_NAME'));

You can reference the value of a user preference using the function GET_PREFERENCES. For example:

NVL(HTMLDB_UTIL.GET_PREFERENCE('NAMED_PREFERENCE'),15)

In the previous example, the preference would default to the value 15 if the preference contained no value.

Resetting User Preferences Manually

You can manually purge user preferences for a specific user.

To manually purge preferences for a specific user:

  1. From the Oracle HTML DB Home page select Administration tab.

  2. Under Administration Services, click Manage Users and then Session State.

    The Session State Management page appears.

  3. Click Purge preferences for a selected user.

  4. Specify a user and follow the on-screen instructions.


See Also:

"Administering Session State and User Preferences" for more information on using the Session State Management page

Resetting Preferences Using a Page Process

You can reset user preferences by creating a page process and selecting the process type Reset Preferences.

To reset user preferences using a page process:

  1. Navigate to the appropriate Page Definition. (See "Viewing a Page Definition".)

  2. Under Page Processes, click Create.

    The Create Page Computation Wizard appears.

  3. Specify a process name, sequence, and processing point.

  4. From Type, select Reset Preferences.

  5. Follow the on-screen instructions