Previous	Next		Contents	Index	Glossary

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 executes any active subscriptions by the local system to the Unexpected 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_name	The 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

/*

** If the complete event data is easily available, we can 

** optionally test if any subscriptions to this event 

** require it (rule data = 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);

  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

Unexpected Event