| Previous | Next |  | Contents | Index | Glossary

## Raise

PL/SQL Syntax

`procedure Raise`

         (p_event_name in varchar2,

          p_event_key in varchar2,

          p_event_data in clob default NULL,

          p_parameters in wf_parameter_list_t default NULL);

Description

Raises a local event to the Event Manager. Raise() creates a WF_EVENT_T structure for this event instance and sets the specified event name, event key, event data, and parameter list into the structure.

The event data can be passed to the Event Manager within the call to the Raise() API, or Raise() can obtain the event data itself by calling the Generate function for the event, after first checking whether the event data is required by any subscriptions. You can improve performance by allowing Raise() to run the Generate function and generate the event data only when subscriptions exist that require that data. See: Events and Standard API for an Event Data Generate Function.

If no event data is passed in, Raise() calls Test() to determine whether any active subscriptions reference the event and what the most costly data requirement among these subscriptions is. See: Test.

If any active subscriptions to the event require the event data, then Raise() calls the Generate function for the event to produce the event data. If no Generate function is defined for the event, Oracle Workflow creates a default set of event data using the event name and event key.

When an event is raised, the Event Manager searches for and executes any active subscriptions by the local system to that event with a source type of Local, and also any active subscriptions by the local system to the Any event with a source type of Local. If no active subscriptions exist for the event that was raised (apart from subscriptions to the Any event), then Oracle Workflow raises the Unexpected event and executes any active subscriptions by the local system to that event with a source type of Local.

> Note: The Event Manager does not raise an error if the event is not defined.

> Note: Any exceptions raised during Raise() processing are not trapped, but instead are exposed to the code that called the Raise() procedure. This behavior enables you to use subscriptions and their rule functions to perform validation, with the same results as if the validation logic were coded inline.

Arguments (input) | p_event_nameThe internal name of the event.
p_event_key | A string generated when the event occurs within a program or application. The event key uniquely identifies a specific instance of the event.
p_event_data | An optional set of information about the event that describes what occurred. If you do not pass in the event data, Raise() checks whether the event data is required by any subscriptions and, if it is required, uses the Generate function for the event to generate the event data. See: Events and Standard API for an Event Data Generate Function.
p_parameters | A list of additional parameter name and value pairs.

Example

`declare l_xmldocument varchar2(32000); l_eventdata clob; l_parameter_list wf_parameter_list_t; l_message varchar2(10);`

    begin

    /*

    ** Test if any subscriptions to this event require a message

    */

      l_message := wf_event.test('<EVENT_NAME>');

    /*

    ** If we do require a message, and we have the message now,

    ** set it; else we can just rely on the Event Generate

    ** Function callback code. Then Raise the Event with the

    ** required parameters.

    */

      if l_message = 'MESSAGE' then

        if l_xmldocument is not null then

          dbms_lob.createtemporary(l_eventdata, FALSE,

            DBMS_LOB.CALL);

          dbms_lob.write(l_eventdata, length(l_xmldocument), 1 ,

            l_xmldocument);

          -- Raise the Event with the message

          wf_event.raise( p_event_name => '<EVENT_NAME>',

            p_event_key  => '<EVENT_KEY>',

            p_event_data => l_eventdata,

       p_parameters => l_parameter_list);

        else

          -- Raise the Event without the message

          wf_event.raise( p_event_name => '<EVENT_NAME>',

            p_event_key  => '<EVENT_KEY>',

            p_parameters => l_parameter_list);

        end if;

      elsif

        l_message = 'KEY' then

          -- Raise the Event

          wf_event.raise( p_event_name => <EVENT_NAME>,

            p_event_key  => <EVENT_KEY>,

            p_parameters => l_parameter_list);

      elsif

        l_message = 'NONE' then

          -- No Subscriptions, do nothing

          null;

      end if;

    /*

    ** Up to your own custom code to commit the transaction

    */

      commit;

    /*

    ** Up to your own custom code to handle any major exceptions

    */

    exception

    when others then

    null;

    end;

### See Also

Any Event

Unexpected Event

| Previous | Next |  | Contents | Index | Glossary