Read a record from an audit file.
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
|
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
...
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.