2.9 Managing Session State Values

When building interactive, data-driven web applications, the ability to access and manage session state values is critical. In Oracle Application Express, session state is automatically managed for every page and easily referenced in static HTML or logic controls such as processes or validations.

2.9.1 About Referencing Session State

You can reference item values stored in session state in regions, computations, processes, validations, and branches. An item can be a field, a text area, a password, a select list, or a check box. Table 2-3 describes the supported syntax for referencing item values.

Table 2-3 Syntax for Referencing Item Values

Type Syntax Description

SQL

Standard item syntax:

:MY_ITEM

Syntax for items containing special characters:

:"MY_ITEM"

For items whose names are no longer than 30 characters, precede the item name with a colon (:). Use this syntax for references within a SQL query and within PL/SQL.

To reference page items containing special, multibyte, or unicode characters, wrap the page item name in double quotation marks.

PL/SQL

V('MY_ITEM')

Use PL/SQL syntax to reference an item value using the V function. You can use the shorthand, V function, in place of APEX_UTIL.GET_SESSION_STATE.

Use this syntax when utilizing Oracle Application Express variables directly within an Oracle database object, such as a function, trigger, or Oracle Data Redaction policy.

See Also: Oracle Application Express API Reference

PL/SQL

NV('MY_NUMERIC_ITEM')

Use standard PL/SQL syntax referencing the numeric item value using the NV function. You can use the shorthand, NV function, in place of APEX_UTIL.GET_NUMERIC_SESSION_STATE.

See Also: Oracle Application Express API Reference

Static text (exact)

Standard item syntax:

&MY_ITEM.

Syntax for items containing special characters:

&"MY_ITEM".

For static text or an exact substitution, use the convention &ITEM_NAME followed by a period (.).

To reference page items containing special, multibyte, or unicode characters, wrap the page item name in double quotation marks.


2.9.2 Setting Session State

This section describes how to set value of an item in your application and therefore set session state.

2.9.2.1 About Setting Session State

You can set the value of an item in your application and therefore set session state using the following methods:

2.9.2.2 About Setting Session State with a Form Submission

When a user submits a page, the Application Express engine automatically stores values typed into fields (items) in session state. For example, suppose you have an application containing two pages. The first page of the application contains a form in which a user can enter a phone number. You defined this form by creating an item named P1_PHONENO. On the second page, you want to display the information the user enters in the form.

When the page is submitted, Oracle Application Express captures the value entered in the phone number field and stores the value for future use. On the second page, the phone number entered by the user can then be retrieved from session state using the name P1_PHONE_NO with the appropriate syntax from Table 2-3, "Syntax for Referencing Item Values".

2.9.3 Clearing Session State

As you develop your applications, you may find it useful to clear the cached value for specific items, all items on a page, all pages in an application, or the current user session. Clearing a cached value resets the value to null. This section provides specific examples of clearing session state.

2.9.3.1 About Clearing Cache for an Item

Clearing cache for a single item resets the value of the item to null. For example, you might use this approach to make sure a specific item's value is null when a page is prepared for rendering.

The following example uses standard f?p syntax to clear the cache for an item. This example calls page 5 of application 100. Placing MY_ITEM in the ClearCache position of the f?p syntax resets the value of MY_ITEM to NULL.

f?p=100:5:&APP_SESSION.::NO:MY_ITEM

The following example resets the value of the items THE_EMPNO and THE_DEPTNO:

f?p=100:5:&APP_SESSION.::NO:THE_EMPNO,THE_DEPTNO

2.9.3.2 Clearing Cache for All Page Items

Caching application items is an effective way to maintain session state. However, there are occasions when you may want to clear the cache for all items on a page. For example, suppose you needed to clear all fields on a page when a user clicks a link that creates a new order. By clearing the cache for an entire page, you set the value of all items on the page to null.

2.9.3.2.1 Example: Clearing Cache for Two Pages and Resetting Pagination

This example clears the session cache for two pages and resets pagination.

f?p=6000:6003:&APP_SESSION.::NO:RP,6004,6014 

This example:

  • Runs page 6003 of application 6000 and uses the current session ID.

  • Indicates to not show debug information (NO).

  • Clears all values maintained by the current session's cache for items of pages 6004 and 6014.

  • Resets region pagination (RP) on page 6003 (the requested page).

2.9.3.2.2 Example: Clearing Cache on a Page and Passing an Item Value

This example shows how to implement an update form. It clears existing information and sets the item's value (typically a primary key).

f?p=6000:6003:&APP_SESSION.::NO:6003:MY_ITEM:1234 

This example:

  • Runs page 6003 of application 6000 and uses the current session ID

  • Indicates to not show debug information (NO)

  • Clears all values maintained by the current session's cache for items on page 6003

  • Sets the session state of an item called MY_ITEM to the value 1234

2.9.3.2.3 Example: Clearing Session Cache on a Page and Passing Values to Multiple Items

This example demonstrates how to implement an update form. It clears existing information, sets the item's value (typically a primary key), and passes values to multiple items.

f?p=6000:6004:&APP_SESSION.::NO:6003:MY_ITEM1,MY_ITEM2,MY_ITEM3:1234,,5678 

This example:

  • Runs page 6004 of application 6000 and uses the current session ID

  • Clears the current session's cache for items on page 6003

  • Indicates to not show debug information (NO)

  • Sets the value of MY_ITEM1 to 1234, sets the value of MY_ITEM2 to null (indicated by the comma used as placeholder), and sets the value of MY_ITEM3 to 5678

2.9.3.3 Example: Clearing Cache for an Entire Application

This example clears the application's cache by using f?p syntax and creating a Clear Cache argument using the keyword APP.

f?p=App:Page:Session::NO:APP

2.9.3.4 About Resetting an Application Completely

Resetting the cache for an entire application does not restore the application to a completely reset state. For example, if an application includes on-new instance computations or on-new instance processes, the Application Express engine runs these computations and processes when the application session is created. Then, it processes the clear cache request and displays the requested page.

To reset an application completely without a session ID (if no cookie is used to track the session ID), you must request it using a URL without a session ID, or by calling APEX_UTIL.CLEAR_APP_CACHE from another application. If the session ID is tracked using a cookie, you must logout to reset the state.

2.9.3.5 About Clearing Cache for the Current User Session

Another approach to clearing an application's cache is to create a Clear Cache argument using the keyword SESSION. For example:

f?p=6000:6004:12507785108488427528::NO:SESSION

2.9.4 Referencing Session State Using Bind Variable Syntax

This section describes how to reference session state using bind variable syntax.

2.9.4.1 About Using Bind Variable Syntax

You can use bind variables syntax anywhere in Oracle Application Express where you are using SQL or PL/SQL to reference session state of a specified item. For example:

SELECT * FROM employees WHERE last_name like '%' || :SEARCH_STRING || '%'

In this example, the search string is a page item. If the region type is defined as SQL Query, you can reference the value using standard SQL bind variable syntax. Using bind variables ensures that parsed representations of SQL queries are reused by the database, optimizing memory usage by the server.

When using bind variable syntax, remember the following rules:

  • Bind variable names must correspond to an item name.

  • Bind variable names are not case-sensitive.

  • Bind variable names cannot be longer than 30 characters (that is, they must be a valid Oracle identifier).

    Although page item and application item names can be up to 255 characters, if you intend to use an application item within SQL using bind variable syntax, the item name must be 30 characters or less.

2.9.4.2 About Using Bind Variables in Regions Based on a SQL Query or LOV

If your region type is defined as a SQL Query, SQL Query (plsql function body returning SQL query), or list of values (LOV), you can reference session state using the following syntax:

:MY_ITEM

One common way to do this is to incorporate a session state variable in a WHERE clause. The following example shows how to bind the value of the item THE_DEPTNO into a region defined from a SQL Query.

SELECT last_name, job_id, salary
FROM employees
WHERE department_id = :THE_DEPTNO

See Also:

"About Regions" for information about creating regions

2.9.4.3 About Using Bind Variables in Regions Based on PL/SQL

For region types, processes, computations, validations, conditions, and so on that are defined as PL/SQL dynamic content, regions are constructed using PL/SQL anonymous block syntax. In other words, the beginning and ending keywords are used to enclose the PL/SQL block. For example:

IF :P1_JOB IS NOT NULL THEN
  INSERT INTO employees (employee_id, first_name, job_id) 
  VALUES (:P1_EMP_ID, :P1_NAME, :P1_JOB)
end if;

In this example, the values of the employee_id, first_name, and job_id are populated by the values of P1_EMP_ID, P1_NAME, and P1_JOB.