CBL_AUDIT

Syntax:

call "CBL_AUDIT_EVENT" using by value     flags
                             by reference component-id
                             by reference audit-event
                                returning status-code

Table 1. Parameters
	Typedef	Picture
flags	cblt-x4-comp5	pic x(4) comp-5
component-id	pic x(n)	pic x(n)
audit-event	cblt-aud-event	Group containing
cblte-audevt-version	cblt-x4-comp5	pic x(4) comp-5
cblte-audevt-flags	cblt-x4-comp5	pic x(4) comp-5
cblte-audevt-id	cblt-x4-comp5	pic x(4) comp-5
cblte-audevt-category	cblt-x4-comp5	pic x(4) comp-5
cblte-audevt-data-count	cblt-x4-comp5	pic x(4) comp-5
cblte-audevt-reserved1	cblt-x4-comp5	pic x(4) comp-5 occurs 7
cblte-audevt-event-len	cblt-pointer	pointer
cblte-audevt-event-type	cblt-pointer	pointer
cblte-audevt-event-data	cblt-pointer	pointer
cblte-audevt-reserved2	cblt-pointer	pointer occurs 7

On entry

Control flags

Bit	Value	Meaning
0-12	Reserved	for future use (must be 0)
13	0	cblte-audevt-event-data is an array of pointers to trace data of varying size and type. The corresponding elements of the cblte-audevt-event-len and cblte-audevt-event-type arrays need to be set up.
	1	cblte-audevt-event-data is an array of pointers to trace data of the same size and type. Only the first element of cblte-audevt-event-len and cblte-audevt-event-type need to be set up.
14-29		Reserved for future use (must be 0)
30	0	component-id is space-terminated
	1	component-id is null-terminated
		(ignored if bit 31 unset)
31	0	component-id is an audit handle created by CBL_AUDIT_HANDLE_GET (pic x(4) comp-5).
	1	component-id is a text string (pic x(n)) . The termination character for the string is defined by bit 30.

component-id: Component identifier. This will either be a pic x(4) comp-5 tracer handle (See CBL_AUDIT_HANDLE_GET() - Get an Audit Handle for details about how a component acquires an audit handle) if bit 31 of flags is not set, or a pic x(n) text identifier if bit 31 of flags is set.

cblte-audevt-version: Structure version. Must be 0.

cblte-audevt-flags: Control flags. Must be 0.

cblte-audevt-id: Component specific audit event identifier used to identify the type of event being output

cblte-audevt-category

Category of the audit event being output.

Value Category 
0 Unknown 
1 Audit Facility 
2 System 
3 Security API request check 
4 Security API request define 
5 Security API request other 
6 Security API result allow 
7 Security API result deny 
8 Security API result error 
9 Security API result success

cblte-audevt-data-count: Number of audit data items. Indicates the number of elements in the cblte-audevt-event-len, cblte-audevt-event-type, and cblte-audevt-event-data arrays. May be 0.

cblte-audevt-event-len: Pointer to array of 4-byte comp-5 items. Each array element indicates the length of the corresponding audit data item in the cblte-audevt-event-data array. May be NULL if cblte-audevt-data-count is 0.

cblte-audevt-event-type

Pointer to array of 4-byte comp-5 items. Each array element indicates the type of the corresponding audit data item in the cblte-sudevt-event-data array. May be NULL if cblte-audevt-data-count is 0.

Value Type 
0 Binary 
1 Text (local encoding) 
2 Address 
3 COMP-5 
4 COMP-X 
5 UTF8 
6 Signed COMP-5 
7 Signed COMP-X

cblte-audevt-event-data: Pointer to array of pointer items. Each array element addresses an audit data item of the type and length indicated by the corresponding element in the cblte-audevt-event-type and cblte-audevt-event-len arrays respectively. May be NULL if cblte-audevt-data-count is 0.
N.B. for address type items, the array element is the address value, and not a pointer to the address value.

On Exit:

Nothing

Return Codes:

78-AUD-RET-SUCCESS

78-AUD-RET-INVALID-HANDLE

78-AUD-RET-INVALID-AUDIT-CATEGORY

78-AUD-RET-NOT-ENOUGH-MEMORY

78-AUD-RET-OUTPUT-ERROR

78-AUD-RET-INVALID-COMPONENT-NAME

78-AUD-RET-NO-SERVER-PROCESS

78-AUD-RET-ACCESS-DENIED

78-AUD-RET-TIMEDOUT

Comments:

None

Examples:

copy "mfaudit.cpy".

78 78-EVENT-TYPE-A      value 1.
78 78-EVENT-TYPE-B      value 2.

01 audit-event          cblt-aud-event.
01 audit-event-lengths  pic x(4) comp-5 occurs 1.
01 audit-event-pointers pointer occurs 1.
01 audit-event-types    pic x(4) comp-5 occurs 1.
01 audit-handle         pic x(4) comp-5.
01 audit-info           pic x(10).
01 component-id         pic x(7) value "mycomp ".
01 flags                pic x(4) comp-5.

...
move low-values to audit-event

set cblte-audevt-event-len of audit-event to
    address of audit-event-lengths(1)
set cblte-audevt-event-type of audit-event to
    address of audit-event-types(1)
set cblte-audevt-event-data of audit-event
    to address of audit-event-pointers(1)

1) Acquire an audit handle to trace "mycomp" component audit events, and then output two audit events: one with event data, one without.

call "CBL_AUDIT_HANDLE_GET" using by value 0
                                  by reference component-id
                                  by reference audit-handle
...
move 0 to flags
move 78-AUD-FLAG-CATEGORY-UNKNOWN to
     cblte-audevt-category of audit-event
move 78-EVENT-TYPE-A to cblte-audevt-id of audit-event
move 1 to cblte-audevt-data-count of audit-event
move length of audit-info to audit-event-lengths(1)
move 78-AUDIT-EVENT-TYPE-TEXT to audit-event-types(1)
set audit-event-pointers(1) to address of audit-info

call "CBL_AUDIT_EVENT" using by value flags 
                             by reference audit-handle
                             by reference audit-event
...
move 78-EVENT-TYPE-B to cblte-audevt-id of audit-event
move 0 to cblte-audevt-data-count of audit-event

call "CBL_AUDIT_EVENT" using by value flags 
                             by reference audit-handle
                             by reference audit-event
...

2) Output two informational events for the "mycomp" component without acquiring an audit handle

...
move 78-AUD-FLAG-COMPID-STRING to flags
move 78-AUD-FLAG-CATEGORY-UNKNOWN to
     cblte-audevt-category of audit-event
move 78-EVENT-TYPE-A to cblte-audevt-id of audit-event
move 1 to cblte-audevt-data-count of audit-event
move length of audit-info to audit-event-lengths(1)
move 78-AUDIT-EVENT-TYPE-TEXT to audit-event-types(1)
set audit-event-pointers(1) to address of audit-info

call "CBL_AUDIT_EVENT" using by value flags 
                             by reference component-id
                             by reference audit-event
...
move 78-EVENT-TYPE-B to cblte-audevt-id of audit-event
move 0 to cblte-audevt-data-count of audit-event

call "CBL_AUDIT_EVENT" using by value flags 
                             by reference component-id
                             by reference audit-event
...