Generating application context

Application context allows you to define your own criteria for organizing audit events together. So, for example, you might associate all audit events in the same application context that are generated for an inventory module to help distinguish them from events that are generated for a shipping and receiving module; or you might want to track access to specific windows and controls in a user interface; or you might have a ProDataSet involved in transactions to update multiple databases, and you want to associate the change tracking in that ProDataSet with the appropriate database. Again, you can use the resulting context to structure the reporting of audit events generated in the resulting audit trail.

OpenEdge generates a new application context event record with each call to the SET-APPL-CONTEXT( ) method on the AUDIT-CONTROL system handle. When you want to end the scope of the current application context, call the CLEAR-APPL-CONTEXT( ) method. The syntax for these methods follows:

Syntax

ctx-id = AUDIT-CONTROL:SET-APPL-CONTEXT 
                       (audit-event-ctx[ , event-detail[ , user-data]])
 
logical = AUDIT-CONTROL:CLEAR-APPL-CONTEXT( )

The ctx-id is an application context ID that is a UUID returned as a Base64 character value (with pad characters removed). This application context ID is recorded in all audit event records until the context is changed or cancelled. Each invocation of the SET-APPL-CONTEXT( ) method generates a new application context ID that replaces the previous one in all subsequent audit event records. Thus, only one application context can be active at a time and no nesting of application context is possible.

The input parameters to SET-APPL-CONTEXT( ) are all character values that allow you to specify different levels and types of detailed information about the context, as appropriate for the application. The first, required, parameter specifies an alternate index to the audit event record. So, its length is limited to the maximum size of an index value. Thus, you can use this value as a key for reporting purposes.

If you want to stop recording any application context ID values in audit event records, you must invoke the CLEAR-APPL-CONTEXT( ) method. You can test its logical value for a successful invocation. At no time does the ABL session ever implicitly invoke the CLEAR-APPL-CONTEXT( ) method. Therefore, you must ensure that all code paths (especially error handling code paths) end the application context correctly. You can also begin another application context at any point after clearing the current application context.

If at any point in the ABL session you need to determine the current application context ID, you can examine the value of the APPL-CONTEXT-ID attribute on the AUDIT-CONTROL system handle. This attribute returns the Unknown value (?) if no application context is currently set.

The following code fragments show use of these methods and attributes:

DEFINE VARIABLE user-task AS CHARACTER NO-UNDO.
DEFINE VARIABLE id        AS CHARACTER NO-UNDO.
...
user-task = "Salary adjustments".
...
id = AUDIT-CONTROL:SET-APPL-CONTEXT 
  ("Payroll app", "FICA calculation", user-task).
...
AUDIT-CONTROL:CLEAR-APPL-CONTEXT( ).
...
IF id <> AUDIT-CONTROL:APPL-CONTEXT-D THEN ...