Overview | Package | Object Type | Deprecated | Index | Help
| Oracle9iAS Portal PL/SQL API Reference - 9.0.2.6
PREV TYPE NEXT TYPE | FRAMES NO FRAMES
SUMMARY: ATTRIBUTE | CONSTRUCTOR | FUNCTION/PROCEDURE | DETAIL: ATTRIBUTE | CONSTRUCTOR | FUNCTION/PROCEDURE

## 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 Oracle9iAS Portal. 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

Attribute Summary
`_element_data` | `wwa_module_session_elements`
`_element_lookup` | `wwa_modsess_element_lookup`
`_id` | `integer`
`_module` | `wwa_api_module`
`_shadow_data` | `wwa_module_session_shadow_data`

Function/Procedure Summary
`static build_element_lookup` Builds a look-up table for faster access. | ``
`member clear_shadow` Deletes all data stored in "_shadow_data". | ``
`member copy_attribute_value` Copies attribute values into other instances of the same attribute. | ``
`static create_session` Create a form component session instance. | `wwa_api_module_session`
`static drop_session` Permanently removes form component session data. | ``
`member dump_session` Dumps the contents of the session object for debugging. | ``
`member get_attribute_index` Returns the subscript of the attribute instance in "_element_data" array. | `integer`
`member get_attribute_index` Returns the subscript of the attribute instance in "_element_data" array. | `integer`
`member get_id` Returns the form component session ID. | `integer`
`member get_module` Returns a copy of the form component associated with a session. | `wwa_api_module`
`static get_session` Load an existing form component session instance, first checking for a cached copy. | `wwa_api_module_session`
`member get_shadow_value` Returns the value of an attribute stored in "_shadow_data". | ``
`member get_value_as_date` Returns the value of an attribute (date). | `date`
`member get_value_as_number` Returns the value of an attribute (number). | `number`
`member get_value_as_string` Returns the value of an attribute (NLS formatted string). | `varchar2`
`member get_value_as_varchar2` Returns the value of an attribute (varchar2). | `varchar2`
`static load_session` Loads an existing form component session instance. | `wwa_api_module_session`
`member save_session` Saves form component session data persistently. | ``
`member set_attribute_default` Sets the default value of an attribute to NULL. | ``
`member set_row_default` | ``
`member set_shadow_value` Sets the value of an attribute in "_shadow_data". | ``
`member set_value` Sets the (date, number, varchar2) value of an attribute. | ``
`member set_value` Sets the (date, number, varchar2) value of an attribute. | ``
`member set_value` Sets the (date, number, varchar2) value of an attribute. | ``
`member set_value_as_string` Sets the value of an attribute as a formatted string. | ``
`member transfer_shadow` Moves all data stored in "_shadow_data" to "_element_data". | ``

Attribute Detail

### _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

Function/Procedure Detail

### 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

Overview | Package | Object Type | Deprecated | Index | Help
| Oracle9iAS Portal PL/SQL API Reference - 9.0.2.6
PREV TYPE NEXT TYPE | FRAMES NO FRAMES
SUMMARY: ATTRIBUTE | CONSTRUCTOR | FUNCTION/PROCEDURE | DETAIL: ATTRIBUTE | CONSTRUCTOR | FUNCTION/PROCEDURE