CBL_AUDIT_FILE_READ (deprecated)

Read a record from an audit file.
Note: Audit Manager is deprecated and provided for backward compatibility only. We recommend that you use syslog events instead. See Enterprise Server Auditing for more information.
Restriction: This topic applies only when the Enterprise Server feature is enabled.

Syntax:

call "CBL_AUDIT_FILE_READ" using by value     flags
                                 by value     auditfile-handle
                                 by reference auditfile-record
                                    returning status-code

Parameters:

  Typedef Picture
flags cblt-x4-comp5 pic x(4) comp-5
auditfile-handle cblt-pointer pointer
auditfile-record cblt-aud-record Group containing
cblte-audrec-version cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-flags cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-pid-len cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-tid-len cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-pid-32 cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-pid-64 cblt-x8-comp5 pic x(8) comp-5 redefines cblte-audrec-pid-32
cblte-audrec-tid-32 cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-tid-64 cblt-x8-comp5 pic x(8) comp-5 redefines cblte-audrec-tid-32
cblte-audrec-event-id cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-event-category cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-data-count cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-appname-len cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-cmdline-len cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-os-name-len cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-mc-name-len cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-sys-name-len cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-comp-name-len cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-encoded-time cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-hour cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-minute cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-second cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-millisecond cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-encoded-date cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-year cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-month cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-day cblt-x4-comp5 pic x(4) comp-5
cblte-audrec-reserved1 cblt-x4-comp5 pic x(4) comp-5 occurs 7
cblte-audrec-appname cblt-pointer pointer
cblte-audrec-cmdline cblt-pointer pointer
cblte-audrec-os-name cblt-pointer pointer
cblte-audrec-mc-name cblt-pointer pointer
cblte-audrec-sys-name cblt-pointer pointer
cblte-audrec-comp-name cblt-pointer pointer
cblte-audrec-event-len cblt-pointer pointer
cblte-audrec-event-type cblt-pointer pointer
cblte-audrec-event-data cblt-pointer pointer
cblte-audrec-reserved2 cblt-pointer pointer occurs 7

On Entry:

flags
Bit Value Meaning
0-31   Reserved for future use (must be 0)
Auditfile-handle
Audit handle returned by the CBL_AUDIT_FILE_OPEN API.

On Exit:

cblte-audevt-version
Structure version
cblte-audevt-flags
Control flags
cblte-audrec-pid-len
Length of process identifier (4 or 8)
cblte-audrec-tid-len
Length of thread identifier (4 or 8)
cblte-audrec-pid-32
4-byte process identifier
cblte-audrec-pid-64
8-byte process identifier
cblte-audrec-tid-32
4-byte thread identifier
cblte-audrec-tid-64
8-byte thread identfier
cblte-audrec-event-id
Component specific audit event identifier
cblte-audrec-category
Audit event category
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-audrec-data-count
Number of audit data items. Indicates the number of items in the cblte-audrec-event-len, cblte-audrec-event-type and cblte-audrec-event-data arrays
cblte-audrec-appname-len
Length of application name
cblte-audrec-cmdline-len
Length of command line
cblte-audrec-os-name-len
Length of operating system name
cblte-audrec-mc-name-len
Length of computer/machine name
cblte-audrec-sys-name-len
Length of system name
cblte-audrec-comp-name-len
Length of component name
cblte-audrec-encoded-time
Encoded time of event
cblte-audrec-hour
Decoded hour
cblte-audrec-minute
Decoded minute
cblte-audrec-second
Decoded second
cblte-audrec-millisecond
Decoded millisecond
cblte-audrec-encoded-date
Encoded date of event
cblte-audrec-year
Decoded year
cblte-audrec-month
Decoded month
cblte-audrec-day
Decoded day
cblte-audrec-appname
Pointer to null-terminated name of application that generated audit event
cblte-audrec-cmdline
Pointer to null-terminated command-line of application that generated audit event
cblte-audrec-os-name
Pointer to null-terminated name of operating system that generated audit event
cblte-audrec-mc-name
Pointer to null-terminated name of computer that generated audit event
cblte-audrec-sys-name
Pointer to null-terminated name of system that generated audit event
cblte-audrec-comp-name
Pointer to null-terminated name of component that generated audit event
cblte-audrec-event-len
Pointer to array of 4-byte comp-5 items. Each array element indicates the length of the corresponding audit data item. Will be NULL if cblte-audrec-data-count is 0
cblte-audrec-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-audrec-event-data array. Will be NULL if cblte-audrec-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

Any value other than the ones specified above will be treated as type 0 (binary).

cblte-audrec-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-audrec-event-type and cblte-audrec-event-len arrays respectively. Will be NULL if cblte-audrec-data-count is 0.

Return Codes:

78-AUD-RET-SUCCESS
78-AUD-RET-FAILURE
78-AUD-RET-NOT-ENOUGH-MEMORY
78-AUD-RET-INVALID-HANDLE
78-AUD-RET-FILE-INVALID-FORMAT
78-AUD-RET-FILE-EOF
78-AUD-RET-FILE-NO-MORE-RECORDS

Comments:

CBL_AUDIT_FILE_READ() is used to return the next audit record from the file(s) associated with the current handle.

The function will return 78-AUD-RET-FILE-EOF when attempting to read past the last record in a file for the first time. The next attempt to read past the last record will either return the first record of the next file in the collection if a collection has been opened and another file is available, or 78-AUD-RET-FILE-NO-MORE-RECORDS.

Examples:

copy "mfaudit.cpy ".

01 auditfile-handle  pic x(4) comp-5.
01 auditfile-record  cblt-aud-record.
01 flags             pic x(4) comp-5.
...
compute flags = 0

call "CBL_AUDIT_FILE_READ" using by value flags
                                 by value auditfile-handle
                                 by reference auditfile-record
...