Object Type wwa_api_module_session

This object type contains methods for Oracle Portal form component session storage.

The form component session API object represents the unit of session storage for a form component built using OracleAS Portal 10G. This object can be used to access and manipulate data aspects of a form component for a given session.

An instance of this object exists for each copy of a running form component, for each user.

Working with the session object

The following steps describe the general model for working with this object:

1. Create an instance, using the create_session method.
2. Load an appropriate subset of the data from a source, such as the EMP table, using one of the set_value methods.
3. Save these changes, using the save_session method.
4. Retrieve the session ID, using the get_id method and store the information. Typically this is achieved by saving it in the Web page being generated.
5. Generate the Web page, calling the get_value_as_string method to obtain the (NLS formatted) version of the data value.
6. When a request is received for the session object (passing in the session ID saved in the Web page), load the session object using the ID with the load_session method.
7. Change the content of the object, using one of the set_value methods.
8. Repeat step 3, 4, and 5.

Typically step 2 and step 7 are only performed by user code, whilst the other steps are performed by the Oracle Portal framework.

Access to the data

Attribute values within a form component session are stored in native form. For example, the attribute may have been defined to use the logical type CURRENCY, which has a native implementation type of NUMBER.

Functions within this session storage object permit setting and returning of attribute values in either native form, or in a string representation of the logical type.

The session storage methods access all of the functionality of the session storage object.

Form component session visibility

The storage allocated by this object is visible only within the scope of the Login session that created it. The Login session that created the storage object is defined by calling wwctx_api.get_sessionid.

As a result, it is not possible for multiple users to share the same form component session. Nor is it possible for a single user, operating multiple Login sessions, to access form component sessions across the Login session boundary.

Lifetime of a form component session

After creation, form component sessions exist until they are explicitly dropped using the drop_session method, or are implicitly dropped because the user logs off the system (either explicitly or implicitly).

It is the responsibility of the callers of this object to ensure that any critical data is copied from this object, to more permanent storage, before the session is removed.

Scope:

Public

Since:

Oracle Portal 3.0.9

_element_data

_element_data wwa_module_session_elements

_element_lookup

_element_lookup wwa_modsess_element_lookup

_id

_id integer

_module

_module wwa_api_module

_shadow_data

_shadow_data wwa_module_session_shadow_data

build_element_lookup

static procedure build_element_lookup(
    p_session in out nocopy wwa_api_module_session
) 

Builds a look-up table for faster access.

Use this function to build a lookup-table with a range of "_element_data" array subscripts for each attribute. When the lookup-table exists there is no need to loop through the entire "_element_data" everytime an array subscript of an attribute instance is required.

This method is used in wwa_api_module_session.create_session and wwa_api_module_session.load_session.

Parameters:

p_session - wwa_api_module_session object

Since:

Oracle Portal 3.0.9.8.3

clear_shadow

member procedure clear_shadow

Deletes all data stored in "_shadow_data".

This method is used to delete all data in "_shadow_data", a temporary data structure.

Example:

     declare
         l_session    wwa_api_module_session;
         l_lang       varchar2(50);
     begin
         l_lang := wwctx_api.get_nls_language;
         l_session := wwa_api_module_session.create_session(
                          p_module_id => 123456789,
                          p_version   => 1);
         l_session.set_shadow_value(
             p_block_name     => 'DEFAULT',
             p_attribute_name => 'A_EMPNO',
             p_value          => '7399',
             p_index          => 1,
             p_language       => l_lang);

         l_session.clear_shadow;
     end;
 

Since:

Oracle Portal 3.0.9

copy_attribute_value

member procedure copy_attribute_value(
    p_attribute_name in varchar2 default null,
    p_block_name in varchar2,
    p_source_index in integer default 1,
    p_dest_index in integer default null,
    p_last_dest_index in integer default null
) 

Copies attribute values into other instances of the same attribute.

If no attribute name is specified, the p_source_index instance of each attribute in p_block_name is copied into either:

• p_dest_index instance or,
• p_source_index+1 through p_last_dest_index instances

depending on what information is specified.

Note: To do a bulk copy, only specify p_last_dest_index. If both p_dest_index and p_last_dest_index are specified, then p_dest_index overrides p_last_dest_index.

Example:

Consider a master-detail form component with 50 detail rows. For the detail section, i.e. the DETAIL_BLOCK, the default value of the 1st instance of HIREDATE is set and the value copied into the remaining instances (rather than setting the value for each instance). To set default values for the SAL attribute (instances 7 through 37), set the default value of the 7th instance and then copy this value into instances 8-37:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 9,
           p_version   => 1
       );

       l_session.set_attribute_default
       (
           p_attribute_name => 'A_HIREDATE',
           p_block_name     => 'DETAIL_BLOCK',
           p_index          => 1,
           p_language       => myportal_schema.wwctx_api.get_nls_language
       );

       l_session.copy_attribute_value
       (
           p_attribute_name  => 'A_HIREDATE',
           p_block_name      => 'DETAIL_BLOCK',
           p_last_dest_index => 50
       );

       l_session.set_attribute_default
       (
           p_attribute_name => 'A_SAL',
           p_block_name     => 'DETAIL_BLOCK',
           p_index          => 7,
           p_language       => myportal_schema.wwctx_api.get_nls_language
       );

       l_session.copy_attribute_value
       (
           p_attribute_name  => 'A_SAL',
           p_block_name      => 'DETAIL_BLOCK',
           p_source_index    => 7,
           p_last_dest_index => 37
       );
   end;
 

Parameters:

p_attribute_name - the name of the attribute

p_block_name - the name of the block that owns the attribute

p_source_index - the instance of the attribute from which the value is to be copied

p_dest_index - the instance of the attribute into which the value is to be copied

p_last_dest_index - the last instance of the attribute into which the value is to be copied, i.e., used when the value is to be copied into more than one instance

Since:

Oracle Portal 3.0.9.8.3

create_session

static function create_session(
    p_module_id in integer,
    p_version in integer
) return wwa_api_module_session

Create a form component session instance.

The form component session instance is created in the database and prepared for interaction with the client form. The form component framework calls this API internally before displaying a form component for the first time within a given session, or when instructed to create a new instance of the form component.

Since this is a static function, it should be invoked as:

[portal_schema].wwa_api_module_session.create_session

Example:

Consider an Oracle Portal form component based on the SCOTT.EMP table which has a module_id of 7. To instantiate a session for this form component:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
   end;
 

Parameters:

p_module_id - the ID of the form component for which a session must be instantiated

p_version - the version of the form component. The value 1 is always passed since the session for a form component is not versioned.

Returns:

a wwa_api_module_session object which can be used to manipulate the properties of the newly create storage.

Since:

Oracle Portal 3.0.9

drop_session

static procedure drop_session(
    p_id in integer
) 

Permanently removes form component session data.

This procedure first tries to load the session for the ID specified and then deletes the session data from the database.

Example:

Consider a form component session (id = 77) created and stored in the database using create_session. To drop this session data:

   begin
       myportal_schema.wwa_api_module_session.drop_session
       (
           p_id => 77
       );
   end;
 

Parameters:

p_id - the ID of the form component session to be deleted

Exceptions:

NO_DATA_FOUND - if you try to delete a form session that does not exist, or does not belong to your Login session

Since:

Oracle Portal 3.0.9

dump_session

member procedure dump_session

Dumps the contents of the session object for debugging.

The contents of the session object are dumped using DBMS_OUTPUT.PUT_LINE. Use this procedure for debugging purpose. Use DBMS_OUTPUT.GET_LINE to retrieve the dump from the buffer.

Example:

      declare
          l_session wwa_api_module_session;
      begin
          DBMS_OUTPUT.ENABLE(1000000);
          l_session := wwa_api_module_session.create_session(
                          p_module_id => 123456789,
                          p_version   => 1);
          l_session.dump_session;
          --
          -- Use DBMS_OUTPUT.GET_LINE or DBMS_OUTPUT.GET_LINES
          -- to get the content from the buffer
          --
      end;
 

Since:

Oracle Portal 3.0.9

get_attribute_index

member function get_attribute_index(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_index in integer default 1
) return integer

Returns the subscript of the attribute instance in "_element_data" array.

This method returns the subscript of the attribute instance in "_element_data" array. This method is used by get_value_as_xxxx and set_value methods. Ideally, all data manipulations in the session object should be done using the get and set methods.

Example:

Consider a form module (module id: 123456789) having an attribute named A_EMPNO :

      declare
          l_idx integer;
          l_session wwa_api_module_session;
      begin
          l_session := wwa_api_module_session.create_session;
          l_idx := l_session.get_attribute_index(
                      p_block_name     => 'DEAFULT',
                      p_attribute_name => 'A_EMPNO');
      end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_index - the index of the value, for n-valued attributes

Returns:

the array subscript of the attribute in "_element_data"

Since:

Oracle Portal 3.0.9

get_attribute_index

member function get_attribute_index(
    p_attribute in wwa_api_attribute,
    p_index in integer default 1
) return integer

Returns the subscript of the attribute instance in "_element_data" array.

This is a lower level API and it is used by the previous overload. Users are advised to use the previous overload.

Example:

Consider a form module (module id: 123456789) having an attribute named A_EMPNO belonging to the DEFAULT block :

      declare
          l_idx integer;
          l_session wwa_api_module_session;
          l_attribute wwa_api_attribute;
      begin
          l_session := wwa_api_module_session.create_session;
          l_attribute := l_session."_module".find_attribute(
                             'DEFAULT',
                             'A_EMPNO'
                         );
          l_idx := l_session.get_attribute_index(
                      p_attribute     => l_attribute,
                      p_index         => 1);
      end;
 

Parameters:

p_attribute - the attribute object

p_index - the index of the value, for n-valued attributes

Since:

Oracle Portal 3.0.9

get_id

member function get_id
return integer

Returns the form component session ID.

This ID can subsequently be used with the get_session, load_session and drop_session methods.

Example:

Consider an Oracle Portal form component based on the SCOTT.EMP table (module_id=7). To create a session for this form component, you need to know the ID of the session data created:

   declare
       l_session wwa_api_module_session;
       l_session_id integer;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
       l_session_id := l_session.get_id;
 

Returns:

a form component session ID

Since:

Oracle Portal 3.0.9

get_module

member function get_module
return wwa_api_module

Returns a copy of the form component associated with a session.

Each form component session is associated with an form component.

Example:

Consider that a form (on the SCOTT.EMP table) has been created using the form builder and the module_id for the form is 7. Now you need to retrieve all the form settings in the form of an object.

   declare
       l_form_module wwa_api_module;
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
       l_form_module := l_session.get_module;
   end;
 

Returns:

a copy of the form component associated with a form component session

Since:

Oracle Portal 3.0.9

get_session

static function get_session(
    p_id in integer
) return wwa_api_module_session

Load an existing form component session instance, first checking for a cached copy.

Both load_session and get_session load an existing form component session instance and then return a copy of the form component session.

However, get_session first checks for a copy of the form component session in the cache and if present returns the cached copy. If the form component session is not present in the cache, load_session is called to load a fresh copy from the database, return the newly loaded session and also caches it.

The session storage is located by the combination of the form component session ID parameter (p_id) and the Login session ID (wwctx_api.get_sessionid).

Example:

Consider a form component session (id = 77) previously created and stored in the database using create_session. To retrieve the session:

   declare
       l_session wwa_api_module_session;
   begin
       --- First check the cache for a copy of the form session data,
       --- if cache is absent, load the session data
       --- from the database by calling load_session;
       --- all this is done by get_session
       l_session := myportal_schema.wwa_api_module_session.get_session
       (
           p_id => 77
       );
 

To load the session directly from the database:

    l_session := myportal_schema.wwa_api_module_session.load_session
       (
           p_id => 77
       );
       exception
           when NO_DATA_FOUND then
               ...
            --- The session you are looking for is not
            --- in the database or belongs to a different Login session
   end;
 

Parameters:

p_id - the form component session ID, previously returned by create_session

Returns:

a form component session object

Exceptions:

NO_DATA_FOUND - if you try to get a session that does not exist or that belongs to another Login session

Since:

Oracle Portal 3.0.9

get_shadow_value

member procedure get_shadow_value(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_index in integer default 1,
    p_value in out varchar2,
    p_language in out varchar2
) 

Returns the value of an attribute stored in "_shadow_data".

This method is used to fetch the value of an attribute stored in "_shadow_data", a temporary data structure.

Example:

     declare
         l_session    wwa_api_module_session;
         l_lang       varchar2(50);
     begin
         l_lang := wwctx_api.get_nls_language;
         l_session := wwa_api_module_session.create_session(
                          p_module_id => 123456789,
                          p_version   => 1);
         l_session.set_shadow_value(
             p_block_name     => 'DEFAULT',
             p_attribute_name => 'A_EMPNO',
             p_value          => '7399',
             p_index          => 1,
             p_language       => l_lang);

         l_session.get_shadow_value(
             p_block_name     => 'DEFAULT',
             p_attribute_name => 'A_EMPNO',
             p_value          => l_value,
             p_index          => 1,
             p_language       => l_lang);
     end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_index - the index of the value, for n-valued attributes

p_value - in out parameter to return the value

p_language - current language chosen for Portal

Since:

Oracle Portal 3.0.9

get_value_as_date

member function get_value_as_date(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_index in integer default 1
) return date

Returns the value of an attribute (date).

Call this function to get the (date) value of an attribute in the native form, i.e. without any format masks applied on the values. This function retrieves values set via the set_value procedure.

Example:

To retrieve the value of the HIREDATE attribute of a form component based on a table, i.e. the A_HIREDATE attribute of the session data set using the set_value procedure:

   declare
       l_HIREDATE date;
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
       l_HIREDATE := l_session.get_value_as_date
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_HIREDATE'
       );
   end;
 

To retrieve the values of 2 instances of the HIREDATE attribute for a master-detail form component, i.e. the A_HIREDATE attribute of the session data that was set using the set_value procedure:

   declare
       l_HIREDATE1 date;
       l_HIREDATE2 date;
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 9,
           p_version   => 1
       );
       l_HIREDATE1 := l_session.get_value_as_date
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_HIREDATE',
           p_index          => 1
       );
       l_HIREDATE2 := l_session.get_value_as_date
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_HIREDATE',
           p_index          => 2
       );
   end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_index - the index of the value, for n-valued attributes

Returns:

the attribute as a date

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a DATE column

Since:

Oracle Portal 3.0.9

get_value_as_number

member function get_value_as_number(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_index in integer default 1
) return number

Returns the value of an attribute (number).

Call this function to get the (date) value of an attribute, i.e., without any format masks applied on the values. This function retrieves values set via the set_value procedure.

Example:

To retrieve the value of the EMPNO attribute for a form component based on a table, i.e. the A_EMPNO attribute of the session data that was set using the set_value procedure:

   declare
       l_empno integer;
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
       l_empno := l_session.get_value_as_number
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_EMPNO'
       );
   end;
 

To retrieve the values of 2 instances of the EMPNO attribute for a master-detail form component, i.e. the A_EMPNO attribute of the session data that was set using the set_value procedure.

   declare
       l_empno1 integer;
       l_empno2 integer;
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 9,
           p_version   => 1
       );
       l_empno1 := l_session.get_value_as_number
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_EMPNO',
           p_index          => 1
       );
       l_empno2 := l_session.get_value_as_number
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_EMPNO',
           p_index          => 2
       );
   end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_index - the index of the value, for n-valued attributes

Returns:

the attribute as a number

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a NUMBER column

Since:

Oracle Portal 3.0.9

get_value_as_string

member function get_value_as_string(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_index in integer default 1,
    p_language in varchar2
) return varchar2

Returns the value of an attribute (NLS formatted string).

Call this function to get the value of an attribute as a type-specific NLS formatted string, i.e. to retrieve the value when a format mask is specified at design time.

Example:

Consider an Oracle Portal form component based on the SCOTT.EMP table (module_id=7). The HIREDATE attribute has the format mask fmdd-mm-yyyy hh24:mi:ss.

To retrieve the value of the A_HIREDATE session data attribute, set using the set_value_as_string procedure:

   declare
       l_session wwa_api_module_session;
       l_value  varchar2(4000);
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
       l_value:= l_session.get_value_as_string
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_HIREDATE',
           p_language       => myportal_schema.wwctx_api.get_nls_language
       );
   end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_index - the index of the value, for n-valued attributes

p_language - the language to be used for all value transformations

Returns:

a text string version of the attribute value, transformed according to a set of rules defined against the attribute's type

Since:

Oracle Portal 3.0.9

get_value_as_varchar2

member function get_value_as_varchar2(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_index in integer default 1
) return varchar2

Returns the value of an attribute (varchar2).

Call this function to get the (varchar2) value of an attribute, i.e., without any format masks applied on the values. This function retrieves values set via the set_value procedure.

Example:

To retrieve the value of the ENAME attribute for a form component based on a table, i.e. the A_ENAME attribute of the session data that was set using the set_value procedure:

   declare
       l_ENAME varchar2(4000);
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
       l_empno := l_session.get_value_as_varchar2
       (
           p_block_name => 'DEFAULT',
           p_attribute_name => 'A_ENAME'
       );
   end;
 

To retrieve the values of 2 instances of ENAME attribute for a master-detail form component, i.e. the A_ENAME attribute of the session data that was set using the set_value procedure:

   declare
       l_ENAME1 varchar2(4000);
       l_ENAME2 varchar2(4000);
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 9,
           p_version   => 1
       );
       l_ENAME1 := l_session.get_value_as_varchar2
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_ENAME',
           p_index          => 1
       );
       l_ENAME2 := l_session.get_value_as_varchar2
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_ENAME',
           p_index          => 2
       );
   end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_index - the index of the value, for n-valued attributes

Returns:

a varchar2

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is not a VARCHAR2 column

Since:

Oracle Portal 3.0.9

load_session

static function load_session(
    p_id in integer
) return wwa_api_module_session

Loads an existing form component session instance.

Both load_session and get_session load an existing form component session instance and then return a copy of the form component session.

However, get_session first checks for a copy of the form component session in the cache and if present returns the cached copy. If the form component session is not present in the cache, load_session is called to load a fresh copy from the database, return the newly loaded session and also caches it.

The session storage is located by the combination of the form component session ID parameter (p_id) and the Login session ID (wwctx_api.get_sessionid).

Example:

Consider a form component session (id = 77) previously created and stored in the database using create_session. To retrieve the session:

   declare
       l_session wwa_api_module_session;
   begin
       --- First check the cache for a copy of the form session data,
       --- if cache is absent, load the session data
       --- from the database by calling load_session;
       --- all this is done by get_session
       l_session := myportal_schema.wwa_api_module_session.get_session
       (
           p_id => 77
       );
 

To load the session directly from the database:

       l_session := myportal_schema.wwa_api_module_session.load_session
       (
           p_id => 77
       );
       exception
           when NO_DATA_FOUND then
               ...
            --- The session you are looking for is not
            --- in the database or belongs to a different Login session
   end;
 

Parameters:

p_id - the form component session ID, previously returned by create_session

Returns:

a form component session object

Exceptions:

NO_DATA_FOUND - if you try to load a session that does not exist or that belongs to another Login session

Since:

Oracle Portal 3.0.9

save_session

member procedure save_session

Saves form component session data persistently.

If you use get_session/load_session to retrieve form component session data and then make changes to the session data, the changes are not updated/saved in the database until you invoke save_session.

Example:

Consider a form component session (id = 77) previously created and stored in the database using create_session. To retrieve the session, make changes to the session data and then save the changes:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.get_session
       (
            p_id => 77
       );
           --- Make changes to l_session here ...
           --- Save the changes
       l_session.save_session;
   end;
 

Since:

Oracle Portal 3.0.9

set_attribute_default

member procedure set_attribute_default(
    p_attribute in wwa_api_attribute default null,
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_index in integer default 1,
    p_language in varchar2
) 

Sets the default value of an attribute to NULL.

The default value is specified at design time. If no default value is specified at design time, the attribute's value is set to NULL.

Example:

Consider an Oracle Portal form component based on the SCOTT.EMP table (module_id=7). To set the default value for the HIREDATE attribute in the DEFAULT block:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
       l_session.set_attribute_default
       (
           p_attribute_name => 'A_HIREDATE',
           p_block_name     => 'DEFAULT',
           p_language       => myportal_schema.wwctx_api.get_nls_language
       );
   end;
 

For an Oracle Portal master-detail form component, to set the default value for the 3rd instance of HIREDATE (detail section):

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 9,
           p_version   => 1
       );
       l_session.set_attribute_default
       (
           p_attribute_name => 'A_HIREDATE',
           p_block_name     => 'DEFAULT',
           p_index          => 3,
           p_language       => myportal_schema.wwctx_api.get_nls_language
       );
   end;
 

Parameters:

p_attribute - the attribute object of the attribute whose default value is to be set. If left null, the procedure finds it using the p_attribute_name and p_block_name. This parameter available in Oracle Portal 3.0.9.8.3 and later.

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_index - the index of the value, for n-valued attributes

p_language - the language to be used for all value transformations

Since:

Oracle Portal 3.0.9

set_row_default

member procedure set_row_default(
    p_block_name in varchar2,
    p_index in integer default 1,
    p_language in varchar2
) 

set_shadow_value

member procedure set_shadow_value(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_value in varchar2,
    p_index in integer default 1,
    p_language in varchar2
) 

Sets the value of an attribute in "_shadow_data".

This method is used to set the value of an attribute in "_shadow_data", a temporary data structure. After the form is submitted, user inputs are first stored in "_shadow_data" before they are tranferred to "_element_data". "_shadow_data" typically stores query criteria entered by the user. The query criteria are extracted to form the query.

Example:

     declare
         l_session    wwa_api_module_session;
         l_lang       varchar2(50);
     begin
         l_lang := wwctx_api.get_nls_language;
         l_session := wwa_api_module_session.create_session(
                          p_module_id => 123456789,
                          p_version   => 1);
         l_session.set_shadow_value(
             p_block_name     => 'DEFAULT',
             p_attribute_name => 'A_EMPNO',
             p_value          => '7399',
             p_index          => 1,
             p_language       => l_lang);

         l_session.get_shadow_value(
             p_block_name     => 'DEFAULT',
             p_attribute_name => 'A_EMPNO',
             p_value          => l_value,
             p_index          => 1,
             p_language       => l_lang);
     end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_value - the value to be set for the attribute

p_index - the index of the value, for n-valued attributes

p_language - current language chosen for Portal

Since:

Oracle Portal 3.0.9

set_value

member procedure set_value(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_value in date,
    p_index in integer default 1
) 

Sets the (date, number, varchar2) value of an attribute.

If the name of a form component attribute is EMPNO, the name of the attribute in the session data would be A_EMPNO.

If you build a form component based on a table/view, session data attributes are available under the block named DEFAULT. If you build a master-detail form, the corresponding session data attributes for the master section are available under the block named MASTER_BLOCK and the detail section are available under DETAIL_BLOCK.

Example 1:

Consider an Oracle Portal form component based on the SCOTT.EMP table (module_id=7). To set values for the EMPNO, ENAME and HIREDATE attributes, i.e. A_EMPNO, A_ENAME and A_HIREDATE session data attributes:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );

       --- Setting value for A_EMPNO i.e. EMPNO attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_EMPNO',
           p_value          => 555
       );

       --- Setting value for A_ENAME i.e. ENAME attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_ENAME',
           p_value          => 'NEW EMP'
        );

       --- Setting value for A_HIREDATE i.e HIREDATE attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_HIREDATE',
           p_value          => to_date('14-FEB-01','DD-MON-RR')
       );
   end;
 

As this form component is based on a table/view, there is a single instance of each form attribute. Therefore the index is not passed and it takes the default value of 1.

For a master-detail form component the detail section has 'n' instances of a detail section attribute. Where n=number of detail rows, as specified in the detail section while building the form.

Example 2:

Consider an Oracle Portal master-detail form component built on the DEPT-EMP table where the number of detail rows is 5. If the module_id of the form component is 9, to set the values of the DNAME form attribute and the first two instances of the EMPNO attribute:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 9,
           p_version   => 1
       );

       --- Setting value of the A_DNAME i.e DNAME attribute of MASTER
       l_session.set_value
       (
           p_block_name     => 'MASTER_BLOCK',
           p_attribute_name => 'A_DNAME',
           p_value          => 'NEW DEPT'
       );

       --- Setting values of the A_EMPNO i.e EMPNO attribute of DETAIL
       l_session.set_value
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_EMPNO',
           p_value          => 777,
           p_index          => 1
       );

       l_session.set_value
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_EMPNO',
           p_value          => 999,
           p_index          => 2
       );
   end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_value - the value of the attribute

p_index - the index of the value, for n-valued attributes

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is incorrect

Since:

Oracle Portal 3.0.9

set_value

member procedure set_value(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_value in number,
    p_index in integer default 1
) 

Sets the (date, number, varchar2) value of an attribute.

If the name of a form component attribute is EMPNO, the name of the attribute in the session data would be A_EMPNO.

If you build a form component based on a table/view, session data attributes are available under the block named DEFAULT. If you build a master-detail form, the corresponding session data attributes for the master section are available under the block named MASTER_BLOCK and the detail section are available under DETAIL_BLOCK.

Example 1:

Consider an Oracle Portal form component based on the SCOTT.EMP table (module_id=7). To set values for the EMPNO, ENAME and HIREDATE attributes, i.e. A_EMPNO, A_ENAME and A_HIREDATE session data attributes:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );

       --- Setting value for A_EMPNO i.e. EMPNO attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_EMPNO',
           p_value          => 555
       );

       --- Setting value for A_ENAME i.e. ENAME attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_ENAME',
           p_value          => 'NEW EMP');

       --- Setting value for A_HIREDATE i.e HIREDATE attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_HIREDATE',
           p_value          => to_date('14-FEB-01','DD-MON-RR')
       );
   end;
 

As this form component is based on a table/view, there is a single instance of each form attribute. Therefore the index is not passed and it takes the default value of 1.

For a master-detail form component the detail section has 'n' instances of a detail section attribute. Where n=number of detail rows, as specified in the detail section while building the form.

Example 2:

Consider an Oracle Portal master-detail form component built on the DEPT-EMP table where the number of detail rows is 5. If the module_id of the form component is 9, to set the values of the DNAME form attribute and the first two instances of the EMPNO attribute:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 9,
           p_version   => 1
       );

       --- Setting value of the A_DNAME i.e DNAME attribute of MASTER
       l_session.set_value
       (
           p_block_name     => 'MASTER_BLOCK',
           p_attribute_name => 'A_DNAME',
           p_value          => 'NEW DEPT'
       );

       --- Setting values of the A_EMPNO i.e EMPNO attribute of DETAIL
       l_session.set_value
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_EMPNO',
           p_value          => 777,
           p_index          => 1
       );

       l_session.set_value
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_EMPNO',
           p_value          => 999,
           p_index          => 2
       );
   end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_value - the value of the attribute

p_index - the index of the value, for n-valued attributes

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is incorrect

Since:

Oracle Portal 3.0.9

set_value

member procedure set_value(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_value in varchar2,
    p_index in integer default 1
) 

Sets the (date, number, varchar2) value of an attribute.

If the name of a form component attribute is EMPNO, the name of the attribute in the session data would be A_EMPNO.

If you build a form component based on a table/view, session data attributes are available under the block named DEFAULT. If you build a master-detail form, the corresponding session data attributes for the master section are available under the block named MASTER_BLOCK and the detail section are available under DETAIL_BLOCK.

Example 1:

Consider an Oracle Portal form component based on the SCOTT.EMP table (module_id=7). To set values for the EMPNO, ENAME and HIREDATE attributes, i.e. A_EMPNO, A_ENAME and A_HIREDATE session data attributes:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );

       --- Setting value for A_EMPNO i.e. EMPNO attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_EMPNO',
           p_value          => 555
       );

       --- Setting value for A_ENAME i.e. ENAME attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_ENAME',
           p_value          => 'NEW EMP');

       --- Setting value for A_HIREDATE i.e HIREDATE attribute of the form
       l_session.set_value
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_HIREDATE',
           p_value          => to_date('14-FEB-01','DD-MON-RR')
       );
   end;
 

As this form component is based on a table/view, there is a single instance of each form attribute. Therefore the index is not passed and it takes the default value of 1.

For a master-detail form component the detail section has 'n' instances of a detail section attribute. Where n=number of detail rows, as specified in the detail section while building the form.

Example 2:

Consider an Oracle Portal master-detail form component built on the DEPT-EMP table where the number of detail rows is 5. If the module_id of the form component is 9, to set the values of the DNAME form attribute and the first two instances of the EMPNO attribute:

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 9,
           p_version   => 1
       );

       --- Setting value of the A_DNAME i.e DNAME attribute of MASTER
       l_session.set_value
       (
           p_block_name     => 'MASTER_BLOCK',
           p_attribute_name => 'A_DNAME',
           p_value          => 'NEW DEPT'
       );

       --- Setting values of the A_EMPNO i.e EMPNO attribute of DETAIL
       l_session.set_value
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_EMPNO',
           p_value          => 777,
           p_index          => 1
       );

       l_session.set_value
       (
           p_block_name     => 'DETAIL_BLOCK',
           p_attribute_name => 'A_EMPNO',
           p_value          => 999,
           p_index          => 2
       );
   end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_value - the value of the attribute

p_index - the index of the value, for n-valued attributes

Exceptions:

VALUE_ERROR - if the attribute's type indicates that the implementation type is incorrect

Since:

Oracle Portal 3.0.9

set_value_as_string

member procedure set_value_as_string(
    p_block_name in varchar2,
    p_attribute_name in varchar2,
    p_value in varchar2,
    p_index in integer default 1,
    p_language in varchar2
) 

Sets the value of an attribute as a formatted string.

Call this procedure to set the value of an attribute when you specify the value as a formatted string, i.e. in accordance with the format mask specified at design time.

Note: If no format mask is specified at design time, conversion is tried with one of the preset format masks.

Example:

Consider an Oracle Portal form component based on the SCOTT.EMP table (module_id=7). The HIREDATE attribute has the format mask fmdd-mm-yyyy hh24:mi:ss.

   declare
       l_session wwa_api_module_session;
   begin
       l_session := myportal_schema.wwa_api_module_session.create_session
       (
           p_module_id => 7,
           p_version   => 1
       );
       l_session.set_value_as_string
       (
           p_block_name     => 'DEFAULT',
           p_attribute_name => 'A_HIREDATE',
           p_value          => '14-02-2001 09:30:00',
           p_language       => myportal_schema.wwctx_api.get_nls_language
       );
   end;
 

Parameters:

p_block_name - the name of the block that owns the attribute

p_attribute_name - the name of the attribute

p_value - the value of the attribute

p_index - the index of the value, for n-valued attributes

p_language - the language to be used for all value transformations

Exceptions:

VALUE_ERROR - if the transformation could not be performed, due to formatting problems with the input data

Since:

Oracle Portal 3.0.9

transfer_shadow

member procedure transfer_shadow

Moves all data stored in "_shadow_data" to "_element_data".

This method is used to move all data stored in "_shadow_data" to the corresponding attributes in "_element_data". The values are moved either to the number_data, varchar2_data or date_data attributes of "_element_data" depending on the datatype of the attribute.

Example:

     declare
         l_session    wwa_api_module_session;
         l_lang       varchar2(50);
     begin
         l_lang := wwctx_api.get_nls_language;
         l_session := wwa_api_module_session.create_session(
                          p_module_id => 123456789,
                          p_version   => 1);

         l_session.set_shadow_value(
             p_block_name     => 'DEFAULT',
             p_attribute_name => 'A_EMPNO',
             p_value          => '7399',
             p_index          => 1,
             p_language       => l_lang);

         l_session.transfer_shadow;
     end;
 

Since:

Oracle Portal 3.0.9