Subject:  EVENT: Summary Event Syntax for WWCS 
Creation Date:  10-DEC-1997 

This is a short description of the most common forms of specifying an
Oracle EVENT.	For the FULL Event syntax see 	 [NOTE:9331.1]
		Setting Events from Oracle Tools [NOTE:45219.1]
		For a list of common ACTIONS see <Event:List>
		For COMMON numeric events see    <Event:Numeric>


Things WWCS use events for:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
  1. To get an IMMEDIATE dump of diagnostic information.
  2. To get a dump of diagnostic information when an error occurs.
  3. To enable / disable focused diagnostic trace output.
  4. To enable / disable or trigger hidden features or options.

Ways to set an event:
~~~~~~~~~~~~~~~~~~~~~
  A. In INIT.ORA	
  B. In the current SQL session
  C. In another session from SQL
  D. In another session from a debug tool. 
	See <SupTool:OraDebug>, <SupTool:OraDBX> and <SupTool:OraMBX>


1. IMMEDIATE dumps of Diagnostic information: (XXX=Action, N=level)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  In INIT.ORA:	   No, does not make sense
  Current session: ALTER SESSION SET EVENTS 'immediate trace name XXX level N';
  Another session: sys.dbms_system.set_ev(SID,SERIAL, 65535, N,'XXX' );
		   ** Note: This is NOT truely IMMEDIATE. The target session 
			    should pick up this event as soon as it can.
  Debug Tool: 	   ** Note: Not all platforms allow asynchronous interrupts of 
			    a session, notably: Windows (including NT) and MVS. 

   svrmgrl: 	   oradebug setospid PID
 
		   oradebug DUMP XXX N
   oradbx:  	   debug PID 
		   event IMMEDIATE trace name XXX level N
                   (e.g event IMMEDIATE trace name processstate level 10)

   orambx:  	   Enter Process name: 
		    event IMMEDIATE trace name XXX level N

2. When an error occurs: (XXX=Action, N=Level, EEE=Error to trigger on)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  In INIT.ORA:	   event="EEE trace name XXX level N"
  Current session: ALTER SESSION SET EVENTS 'EEE trace name XXX level N';
  Another session: sys.dbms_system.set_ev(SID,SERIAL, EEE, N, 'XXX');
  Debug Tool: 	   
   svrmgrl: 	   oradebug setospid PID
		   oradebug event EEE trace name XXX level N
   oradbx:  	   debug PID 
		   event EEE trace name XXX level N
   orambx:  	   Enter Process name: 
		     event EEE trace name XXX level N

3. To enable / disable diagnostic trace output: (VVVVV=Event number)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  The error numbers 10000 to 10999 are reserved for debug event codes.
  For the most common of the 'numeric events' see <Event:Numeric>

  Usually an event just needs setting to a level and no action is actually
  required. For this the action is 'CONTEXT' rather than a real action. You can
  set a real action also if it is required. 

  ** Note: the syntax here is slightly different. Note the COMMA after the
  	   keyword 'forever'.

  In INIT.ORA:	   event="VVVVV trace name context forever, level N"
  Current session: ALTER SESSION SET EVENTS 
			 'VVVVV trace name context forever, level N';
  Another session: sys.dbms_system.set_ev(SID,SERIAL, VVVVV, N, '');
  Debug Tool: 	   
   svrmgrl: 	   oradebug setospid PID
		   oradebug event VVVVV trace name context forever, level  N
   oradbx:  	   debug PID 
		   event VVVVV trace name context forever, level N
   orambx:  	   Enter Process name: 
		     event VVVVV trace name context forever, level N

4. To enable / disable or trigger hidden features. 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  This is exactly the same as section '3' above. The 'number' of the event
  is one specially reserved to enable / disable a particular feature.
  


Setting Multiple Events
~~~~~~~~~~~~~~~~~~~~~~~
  In INIT.ORA:     Multiple EVENT lines must be colocated or only last is used.
		   This is due to the generic parsing of the init.ora values.
  		   ** Note: INIT.ORA on Personal Oracle 7 see [NOTE:37882.1]
		Eg: event="1000 trace name errorstack level 3"
		    event="60 trace name systemstate level 10"
  Current session: Issue multiple 'ALTER SESSION' commands.
  Another session: Issue multiple 'sys.dbms_system.set_ev' commands
  Debug Tool:      Issue multiple requests.


Setting multiple Actions on an Event
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  ** Note: that you must use the syntax below for multiple actions on the
	   same triggering event number / error.

  General syntax:  'eee TRACE NAME xxx LEVEL n; NAME xxx2 LEVEL n2'
  Eg: event="4030 trace name HEAPDUMP level 1; name ERRORSTACK level 3"

  This syntax can be used in all methods EXCEPT from dbms_system.set_ev();

  Multiple actions are particularly useful where HEAPDUMPS are required
  prior to 7.3 as you can dump the UGA and PGA on the same trigger.

  ** Note: The order of OUTPUT in the tracefile may not match the order in 
	   which you list the 'actions' in the event specification.


Useful additional notes
~~~~~~~~~~~~~~~~~~~~~~~
  Whenever possible UNLIMIT the trace file size.

  SQL in 7.3:  alter session set max_dump_file_size= ... ;
  svrmgrl:     oradebug unlimit 
  oradbx:      unlimit trace
  orambx:      -

  SQL in 7.3 you can redirect trace using 'alter session set user_dump_dest=..'