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,
      p_send_date in date 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, parameter list, and send date into the structure.

The event data can be passed to the Event Manager within the call to the Raise() API, or the Event Manager can obtain the event data itself by calling the Generate function for the event, after first checking whether the event data is required by a subscription. If the event data is not already available in your application, you can improve performance by allowing the Event Manager to run the Generate function and generate the event data only when subscriptions exist that require that data, rather than always generating the event data from your application at runtime. See: Events, Oracle Workflow Developer's Guide and Standard API for an Event Data Generate Function, Oracle Workflow Developer's Guide.

The send date can optionally be set to indicate when the event should become available for subscription processing. If the send date is null, Raise() sets the send date to the current system date. You can defer an event by setting the send date to a date later than the system date. In this case, the Event Manager places the event message on the standard WF_DEFERRED queue, where it remains in a WAIT state until the send date. When the send date arrives, the event message becomes available for dequeuing and will be dequeued the next time an agent listener runs on the WF_DEFERRED queue.

Note: If an event is deferred when it is raised, the event retains its original Local source type when it is dequeued from the WF_DEFERRED queue.

When an event is raised and is not deferred, or when an event that was deferred is dequeued from the WF_DEFERRED queue, the Event Manager begins subscription processing for the event. 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.

The Event Manager checks each subscription before executing it to determine whether the subscription requires the event data. If the event data is required but is not already provided, the Event Manager calls the Generate function for the event to produce the event data. If the event data is required but no Generate function is defined for the event, Oracle Workflow creates a default set of event data using the event name and event key.

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)

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

Any Event, Oracle Workflow Developer's Guide

Unexpected Event, Oracle Workflow Developer's Guide

Copyright © 2003 Oracle Corporation.
All rights reserved.