Audit Application Program Interface › $NMAUAPI OPT=RAISE-EVENT—Raise Audit Events

$NMAUAPI OPT=RAISE-EVENT—Raise Audit Events

The $NMAUAPI OPT=RAISE-EVENT API option raises events that can be used for auditing.

This API option has the following format:

$NMAUAPI [OPT=RAISE-EVENT]
         [TYPE=event_type]
          OBJCLASS=#class
          OBJNAME=object_name
         [OBJLOC=object_location]
         [OBJTEXT=object_text]
         [USER=user_name]
         [USERLOC=user_location]
          ACTION=action_type
         [TEXT=action_text]
         [VALUE=action_value]
         [PERIOD=event_statistics_interval]
         [RMTSYS=remote_regions]
         [TRACE={NO | YES}]

OPT=RAISE-EVENT

(Optional) Specifies that an event be raised for an activity that matches the other parameters.

TYPE=event_type

(Optional) Specifies the type of events to be raised.

Default: APPLICATION

Valid values: ACCESS, APPLICATION, CONFIGURATION, PROCEDURAL, SERVICEABILITY, and UTILIZATION (or UTILISATION)

Note: You use UTILIZATION when your application collects its own statistics. You can let the API collect statistics for you by using the counter options. If you use the counter options, the API will raise the events automatically and you do not have to use this RAISE-EVENT option.

OBJCLASS=#class

Specifies the class (user-defined) of the objects to be audited. The class name must start with # (for example, #CLASS01).

Limits: Eight characters, including #

OBJNAME=object_name

(Optional for UTILIZATION) Identifies the object for which the event is raised.

OBJLOC=object_location

(Optional) Specifies the ACB name of the region that owns the object.

Limits: Eight characters

OBJTEXT=object_text

(Optional) Specifies a description to further identify the object.

USER=user_name

(Optional) Specifies the ID of the user whose activity raised the event.

Default: ID of the user that calls the API

Limits: Eight characters

USERLOC=user_location

(Optional) Specifies the ACB name of the region in which the user whose activity raised the event is logged on.

Limits: Eight characters

ACTION=action_type

Specifies the performed action. The API provides the following predefined actions:

In SMF, actions are represented in hexadecimal values.

If you specify your own action, it will be recorded in SMF as X'FFFF' (USER-DEFINED) with the TEXT field as action_type:action_text. If you want to assign a specific hexadecimal ID to a user action not in the list, you can define it through Common Application Services (CAS).

Limits: 12 characters

TEXT=action_text

(Optional) Specifies additional information about the action.

Example: For events of the PROCEDURAL type, it can specify a command.

VALUE=action_value

(Mandatory when specifying TYPE=UTILIZATION) Specifies a number to qualify the action.

Limits: Integer

Example: For events of the UTILIZATION type, it can specify the number of suppressed system messages; for events of the PROCEDURAL type, it can specify the return code.

PERIOD=event_statistics_interval

(UTILIZATION only) Specifies the length of the period, in minutes, the event statistics are for.

Limits: Integer

RMTSYS=remote_regions

Specifies a comma-delimited list of the ACB names of the remote regions in which you also want to raise the audit event (for example, when a user performs an action on a remote resource). If the remote region is linked and has auditing enabled for the event type, the event is raised and recorded for that region. For this to be successful, the user that invoked the API must be defined in the remote region.

TRACE

Specifies whether to trace each invocation of the API by writing NMAU0001 messages to the activity log.

TRACE=NO has effect only if the &GLBL$NMAUTRC global variable is not set to YES or Y.

Default: NO