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 enabled subscriptions by the local system to that event with a source type of Local, and also any enabled subscriptions by the local system to the Any event with a source type of Local. If no enabled subscriptions exist for the event that was raised (apart from subscriptions to the Any event), then Oracle Workflow executes any enabled 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)

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. 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. See: Events, Oracle Workflow Developer's Guide and Standard API for an Event Data Generate Function, Oracle Workflow Developer's Guide.
p_parameters	An optional list of additional parameter name and value pairs.
p_send_date	An optional date to indicate when the event should become available for subscription processing.

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, Oracle Workflow Developer's Guide