CBL_AUDIT_FILE_READ

Read a record from an audit file.

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 Control 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
...

Related topics: