BEGIN-EVENT-GROUP( ) method

Indicates (and records) the beginning of a group of related audit events in the current session. Audit event groups are used to group a series of related application and database audit events in one or more connected audit-enabled databases whose current audit policy has this audit event enabled.

This method returns a Base64 character string that specifies the universally unique identifier (UUID) of the primary index for all audit event records generated by this method for this audit event group. This UUID is recorded in all subsequent audit event records until you either end this audit event group or begin a different audit event group. The UUID is 22 characters in length (the two trailing Base64 pad characters are removed).

Return type: CHARACTER

Applies to: AUDIT-CONTROL system handle

Syntax

BEGIN-EVENT-GROUP( event-context[ , event-detail
   [ , audit-custom-detail]] )

event-context

A character expression that specifies the context for the audit event. The value of this expression cannot exceed 200 characters. You can also use this value as an alternate index for querying the audit event record.

If you specify the Unknown value (?), the AVM generates a run-time error.

event-detail

An optional character expression that specifies additional audit detail. The value of this expression cannot exceed 10,000 characters.

audit-custom-detail

An optional character expression that specifies additional user detail. The value of this expression cannot exceed 10,000 characters.

The UUID is saved as the EVENT-GROUP-ID attribute value for each connected audit-enabled database.

There can be only one active event group per session at any one point in time. To set a different event group for the session, you can:

• Call the END-EVENT-GROUP( ) method, to end the current event group, and then call the BEGIN-EVENT-GROUP( ) method to begin the new event group.
• Call the BEGIN-EVENT-GROUP( ) method to begin the new event group. If there is an existing event group in effect, the AVM ends the existing event group before beginning the new event group.

Calling this method generates an audit event, and creates an audit record for the event in all connected audit-enabled databases according to each database's current audit policy settings.

The following code fragment illustrates how to use the BEGIN-EVENT-GROUP( ) method:

DEFINE VARIABLE name   AS CHARACTER NO-UNDO.
DEFINE VARIABLE ctx-id AS CHARACTER NO-UNDO.
DEFINE VARIABLE grp-id AS CHARACTER NO-UNDO.
. . .
grp-id = AUDIT-CONTROL:BEGIN-EVENT-GROUP
  ("Payroll app", "tax calculations", name).
ctx-id = AUDIT-CONTROL:SET-APPL-CONTEXT
  ("Payroll app", "federal tax calculation", name).
. . .
AUDIT-CONTROL:LOG-AUDIT-EVENT(34122, "payroll.fed.tax.nh").
. . .
ctx-id = AUDIT-CONTROL:SET-APPL-CONTEXT
  ("Payroll app", "fica calculation", name).
. . .
AUDIT-CONTROL:LOG-AUDIT-EVENT(34123, "payroll.fed.tax.ma").
. . .
AUDIT-CONTROL:CLEAR-APPL-CONTEXT.
AUDIT-CONTROL:END-EVENT-GROUP.

See also

END-EVENT-GROUP( ) method, EVENT-GROUP-ID attribute