DISPLAY_JOURNAL table function

The DISPLAY_JOURNAL table function returns information about journal entries. It returns information similar to what is returned by the Display Journal (DSPJRN) CL command and the Retrieve Journal Entries (QjoRetrieveJournalEntries) API.

Read syntax diagramSkip visual syntax diagramDISPLAY_JOURNAL( JOURNAL_LIBRARY =>  journal-library , JOURNAL_NAME =>  journal-name ,STARTING_RECEIVER_LIBRARY => receiver-library,STARTING_RECEIVER_NAME => receiver-name,STARTING_TIMESTAMP => starting-timestamp,STARTING_SEQUENCE => starting-sequence,JOURNAL_CODES => journal-codes,JOURNAL_ENTRY_TYPES => journal-types,OBJECT_LIBRARY => object-library,OBJECT_NAME => object-name,OBJECT_OBJTYPE => object-type,OBJECT_MEMBER => object-member,USER => user,JOB => job,PROGRAM => program,ENDING_RECEIVER_LIBRARY => ending-receiver-library,ENDING_RECEIVER_NAME => ending-receiver-name,ENDING_TIMESTAMP => ending-timestamp,ENDING_SEQUENCE => ending-sequence,GENERATE_SYSLOG => generate-syslog,EOF_DELAY => eof-delay)
The schema is QSYS2.
Authorization:
  • You must have *USE authority to the journal and to all requested journal receivers.
  • *OBJEXIST authority is required to the journal if object-name is omitted or if object-name specifies an object that no longer exists.
  • If object-name is *ALL, you must be authorized to every object associated with a journal entry.
journal-library
A character or graphic string expression that identifies the name of the library containing the journal. The name cannot be *LIBL or *CURLIB.
journal-name
A character or graphic string expression that identifies the name of the journal.
receiver-library
A character or graphic string expression that identifies the name of the starting journal receiver library. The name can be *LIBL or *CURLIB.
receiver-name
A character or graphic string expression that identifies the name of the starting journal receiver. If one of the special values *CURRENT, *CURCHAIN, and *CURAVLCHN is specified, the receiver-library value will be ignored. Otherwise, the receiver-name and receiver-library must identify a valid journal receiver.

If no journal receiver is specified, *CURRENT will be used.

starting-timestamp
A timestamp value that specifies the starting timestamp to use.

A value cannot be specified for both starting-timestamp and starting-sequence.

starting-sequence
A decimal expression that identifies the starting sequence number to use. If the starting-sequence value is not found in the receiver range, an error is returned.

A value cannot be specified for both starting-timestamp and starting-sequence.

journal-codes
A character or graphic string expression that lists the journal codes to return. The string can contain the special values of *ALL or *CTL, or it can be a list of one or more journal codes. Journal codes in the string can be separated by one or more separators. Separators are blank and comma. For example, a valid string can be 'RJ' or 'R J' or 'R,J' or 'R, J'.

If no string is provided, *ALL is used.

journal-types
A character or graphic string expression that lists the journal entry types to return. The string can contain the special values of *ALL or *RCD, or it can be a list of one or more journal entry types. Journal entry types in the string can be separated by one or more separators. Separators are blank and comma. For example, a valid string can be 'JFCT' or 'JF CT' or 'JF,CT' or 'JF, CT'.

If no string is provided, *ALL is used.

object-library
A character or graphic string expression that identifies the name of an object library. The values *LIBL and *CURLIB are allowed.
object-name
A character or graphic string expression that identifies the name of an object.

If the object-name contains the special value of *ALL, object-library must contain a library name and object-type must contain a valid object type. Otherwise, object-name, object-library, object-type, and object-member must identify a valid object.

object-type
A character or graphic string expression that identifies the system object type for the object. The value must be *DTAARA, *DTAQ, *FILE, or *LIB.
object-member
A character or graphic string expression that identifies the name of a member. It can be a special value of *FIRST, *ALL, or *NONE or a valid member name. If the object type is not *FILE, the member name is ignored.
user
A character or graphic string expression that identifies the user profile name for the current user of the job. If user is not specified, *ALL is used.
job
A character or graphic string expression that identifies the name of a job. The first 10 characters are the job name, the second 10 characters are the user name, and the last 6 characters are the job number. If job is not specified, *ALL is used.
program
A character or graphic string expression that identifies the name of a program. If program is not specified, *ALL is used.
ending-receiver-library
A character or graphic string expression that identifies the name of the ending journal receiver library. The name can be *LIBL or *CURLIB. If ending-receiver-name is not *CURRENT, a value for ending-receiver-library must be specified.

The value of this parameter is ignored if eof-delay is greater than zero.

ending-receiver-name
A character or graphic string expression that identifies the name of the ending journal receiver. If the special value *CURRENT is specified, the ending-receiver-library value will be ignored. Otherwise, the ending-receiver-name and ending-receiver-library must identify a valid journal receiver.

If ending-receiver-name is not specified, *CURRENT is used.

The value of this parameter is ignored if eof-delay is greater than zero.

ending-timestamp
A timestamp value that specifies the ending timestamp to use.

A value cannot be specified for both ending-timestamp and ending-sequence. This parameter cannot be specified if eof-delay is greater than zero.

ending-sequence
A decimal expression that identifies the ending sequence number to use. If the ending-sequence value is not found in the receiver range, an error is returned.

A value cannot be specified for both ending-timestamp and ending-sequence. This parameter cannot be specified if eof-delay is greater than zero.

generate-syslog
A character or graphic string expression that indicates whether to transform journal entries into syslog formatted detail. Values are:
NO
No syslog information will be returned. The SYSLOG_EVENT, SYSLOG_FACILITY, SYSLOG_SEVERITY, and SYSLOG_PRIORITY columns will contain the null value.
RFC3164
Values will be returned for the SYSLOG_EVENT, SYSLOG_FACILITY, SYSLOG_SEVERITY, and SYSLOG_PRIORITY columns if syslog information is defined for the journal entry. The SYSLOG_EVENT column will contain a syslog header that matches the RFC3164 format as described by the Internet Engineering Task Force (IETF) Request For Comments (RFC) 3164.
RFC5424
Values will be returned for the SYSLOG_EVENT, SYSLOG_FACILITY, SYSLOG_SEVERITY, and SYSLOG_PRIORITY columns if syslog information is defined for the journal entry. The SYSLOG_EVENT column will contain a syslog header that matches the RFC5424 format as described by the Internet Engineering Task Force (IETF) Request For Comments (RFC) 5424.

DISPLAY_JOURNAL only returns syslog information for the audit journal. If RFC3164 or RFC5424 is specified, journal-library must be QSYS and journal-name must be QAUDJRN.

If generate-syslog is not specified or is the null value, NO is used.

eof-delay
An integer expression that specifies the number of seconds to sleep when all audit journal entries have been read. This delay allows the caller to establish a polling service that will continually return rows, sleeping for the specified interval whenever all entries have been processed.

A value of zero indicates no delay is used and a finite set of rows will be returned. A value greater than zero indicates that the table function will sleep, as needed, to wait for new audit journal entries and never end. If eof-delay is not specified or is the null value, zero is used.

If this parameter has a value greater than zero, the generate-syslog parameter must be RFC3164 or RFC5424, the ending-receiver-library and ending-receiver-name are ignored, and the ending-timestamp and ending-sequence parameters cannot be specified with a value other than their default values.

When using a non-zero eof-delay parameter, avoid using query clauses that depend on returning a finite number of rows. For example, using the FETCH FIRST n ROWS clause can cause the query to end when the requested number of rows has been satisfied. A query using the DISPLAY_JOURNAL function with a non-zero eof-delay parameter does not allow data to be copied (ALWCPYDTA(*NO)). This means that a query requiring a copy of data, such as one using an ORDER BY clause or UNION DISTINCT, will issue an error and not be allowed.

The special values supported for the function arguments are the same as for the Display Journal (DSPJRN) CL command.

The result of the function is a table containing rows with the format shown in the following table. All the columns are nullable.
Table 1. DISPLAY_JOURNAL table function
Column Name Data Type Description
ENTRY_TIMESTAMP TIMESTAMP The system date and time when the journal entry was added to the journal receiver.
SEQUENCE_NUMBER DECIMAL(21,0) A number assigned by the system to each journal entry.
JOURNAL_CODE CHAR(1) The primary category of the journal entry.
JOURNAL_ENTRY_TYPE CHAR(2) Further identifies the type of user-created or system-created entry.
COUNT_OR_RRN BIGINT Contains either the relative record number (RRN) of the record that caused the journal entry or a count that is pertinent to the specific type of journal entry.
ENTRY_DATA BLOB(2G) The entry specific data returned for this journal entry.
NULL_VALUE_INDICATORS VARCHAR(8000) The null value indicators returned for this journal entry.
OBJECT VARCHAR(30) The name of the object for which the journal entry was added.
OBJECT_TYPE VARCHAR(10) The type of object in the entry.
OBJECT_TYPE_INDICATOR CHAR(1) An indicator with respect to the information in the object field.
FILE_TYPE_INDICATOR CHAR(1) Identifies whether or not this journal entry is associated with a logical file.
JOURNAL_IDENTIFIER VARCHAR(10) The journal identifier (JID) for the object.
CURRENT_USER VARCHAR(10) The name of the effective user profile under which the job was running when the entry was created.
JOB_NAME VARCHAR(10) The name of the job that added the entry.
JOB_USER VARCHAR(10) The user profile name of the user that started the job.
JOB_NUMBER VARCHAR(6) The job number of the job that added the entry.
THREAD BIGINT Identifies the thread within the process that added the journal entry.
PROGRAM_NAME VARCHAR(10) The name of the program that added the entry.
PROGRAM_LIBRARY VARCHAR(10) The name of the library that contains the program that added the journal entry.
PROGRAM_LIBRARY_ASP_DEVICE VARCHAR(10) The name of the ASP device that contains the program.
PROGRAM_LIBRARY_ASP_NUMBER INTEGER The number for the auxiliary storage pool that contains the program that added the journal entry.
COMMIT_CYCLE DECIMAL(21,0) A number that identifies the commit cycle.
NESTED_COMMIT_LEVEL BIGINT Indicates the nesting level of the commit cycle that was open when a journal entry representing an object level change was deposited.
XID VARCHAR(140) The transaction identifier, as defined by the Open Group's XA specification, for commit cycles related to an XA transaction branch.
LUW VARCHAR(39) The logical unit of work identifies entries to be associated with a given unit of work.
REMOTE_PORT INTEGER The port number of the remote address associated with this journal entry.
REMOTE_ADDRESS VARCHAR(46) The remote address associated with the journal entry.
SYSTEM_NAME VARCHAR(8) The name of the system on which the entry is being retrieved.
SYSTEM_SEQUENCE_NUMBER DECIMAL(21,0) The system sequence number indicates the relative sequence of when this journal entry was deposited into the journal.
REFERENTIAL_CONSTRAINT CHAR(1) Whether this entry was recorded for actions that occurred on records that are part of a referential constraint.
TRIGGER CHAR(1) Whether this entry was created as result of a trigger program.
IGNORE_ON_APPLY CHAR(1) Whether this entry is ignored during an Apply Journaled Changes (APYJRNCHG) or Remove Journaled Changed (RMVJRNCHG) command.
MINIMIZED_ENTRY_DATA CHAR(1) Whether this entry has minimized entry specific data as a result of the journal having specified MINENTDTA for the object type of the entry.
MINIMIZED_ON_FIELD_BOUNDARY CHAR(1) Whether this entry has minimized entry specific data on field boundaries as a result of the journal having been specified with MINENTDTA(*FLDBDY).
INDICATOR_FLAG CHAR(1) An indicator for the operation.
RECEIVER_NAME VARCHAR(10) The name of the receiver holding the journal entry.
RECEIVER_LIBRARY VARCHAR(10) The name of the library containing the receiver holding the journal entry.
RECEIVER_ASP_DEVICE VARCHAR(10) The name of the ASP device containing the receiver holding the journal entry.
RECEIVER_ASP_NUMBER INTEGER The number for the auxiliary storage pool containing the receiver holding the journal entry.
ARM_NUMBER INTEGER The number of the disk arm that contains the journal entry.
OBJECT_ASP_DEVICE VARCHAR(10) ASP device name.
OBJECT_ASP_NUMBER INTEGER ASP number.
PARENT_FILE_ID BINARY(16) File ID for parent directory.
OBJECT_FILE_ID BINARY(16) File ID for object.
RELATIVE_DIRECTORY_FILE_ID BINARY(16) File ID of directory containing object in PATH_NAME.
OBJECT_FILE_NAME
VARGRAPHIC(2002)
CCSID 1200
 Object name.
PATH_NAME
DBCLOB(16M)
CCSID 1200
 Name of IFS path.
DLO_NAME VARCHAR(12) DLO name.
FOLDER_PATH VARCHAR(63) DLO folder path.
SYSLOG_EVENT VARGRAPHIC(2048) CCSID 1200 The Common Event Format (CEF) syslog event for the journal entry preceded with a header of the requested type. If a header-type of RFC3164 is requested, the maximum length is 1024 characters. If a header-type of RFC5424 is requested, the maximum length is 2048 characters. The string will be truncated with no warning if it exceeds the maximum length.

The audit journal entry types that generate syslog information and the key names returned for journal entries are listed in the Notes section.

Contains the null value if there is no syslog event defined for the journal entry or if NO was specified for the GENERATE_SYSLOG parameter.
SYSLOG_FACILITY INTEGER The syslog facility assigned to the event.
4
security/authorization messages

Contains the null value if there is no syslog event defined for the journal entry or if NO was specified for the GENERATE_SYSLOG parameter.
SYSLOG_SEVERITY INTEGER The syslog severity assigned to the event.
2
Critical condition
4
Warning condition
5
Notice: A normal but significant condition
6
Informational message

The severity assigned to each journal entry is listed in the Notes section.

Contains the null value if there is no syslog event defined for the journal entry or if NO was specified for the GENERATE_SYSLOG parameter.
SYSLOG_PRIORITY INTEGER The syslog priority number assigned to the event.

Contains the null value if there is no syslog event defined for the journal entry or if NO was specified for the GENERATE_SYSLOG parameter.

Note

Row and column access control: This table function recognizes whether ROW ACCESS CONTROL or COLUMN ACCESS CONTROL exists and is activated for the target table. If any row or column access control is active for the table, the rule text logic defined for the row permissions and/or column masks is applied before returning the value in ENTRY_DATA. When the rule text for a row permission determines that the user invoking the function should not see the row, the ENTRY_DATA column contains the text NOT AUTHORIZED. If the user is allowed to see the row and a column mask exists, the rule text for the column mask determines the value returned for ENTRY_DATA.

Syslog information: Syslog information is returned for a subset of audit journal entries. Syslog information is also available for history log messages. See HISTORY_LOG_INFO table function for more details.

The following audit journal entries can generate syslog information:
AD
Auditing changes
AF
Authority failure
AX
Row and column access control
CA
Authority changes
CD
Command string audit
CO
Create object
CP
User profile changed, created, or restored
DO
Delete object
DS
DST security password reset
GR
Generic record
GS
Socket description was given to another job
LD
Link, unlink, or look up directory entry
OM
Object move or rename
OR
Object restore
OW
Object ownership changed
PA
Program changed to adopt authority
PG
Change of an object’s primary group
PW
Invalid password
RA
Authority change during restore
RJ
Restoring job description with user profile specified
RO
Change of object owner during restore
RP
Restoring adopted authority program
RU
Restoring user profile authority
RZ
Changing a primary group during restore
SE
Subsystem routing entry changed
SO
Server security user information actions
ST
Use of service tools
SV
System value changed
ZC
Object accessed (change)
ZR
Object accessed (read)
The audit journal entries are assigned a SYSLOG_SEVERITY value in the following way:
  • Severity 2 Critical condition
    • SV - System value when QAUDCTL is changed to *NONE
  • Severity 4 Warning condition
    • AF - Authority failure
    • GR - Generic record, when function usage was checked and failed for a function name with a prefix of QIBM_DB_
  • Severity 5 Notice: A normal but significant condition
    • AD - Auditing changes
    • AX - Row and column access control
    • CA - Authority changes
    • CP - User profile changed, created, or restored
    • DS - DST security password reset
    • OM - Object move or rename
    • OW - Object ownership changed
    • PG - Change of an object’s primary group
    • PW - Invalid password
    • RA - Authority change during restore
    • RO - Change of object owner during restore
    • RU - Restoring user profile authority
    • RZ - Change a primary group during restore
    • SO - Server security user information actions
  • Severity 6 Informational message
    • CD - Command string audit
    • CO - Create object
    • DO - Delete object
    • GR - Generic record, except for the Severity 4 case where function usage was checked and failed
    • GS - Socket description was given to another job
    • LD - Link, unlink, or look up directory entry
    • OR - Object restore
    • PA - Program changed to adopt authority
    • RJ - Restoring job description with user profile specified
    • RP - Restoring adopted authority program
    • SE - Subsystem routing entry changed
    • ST - Use of service tools
    • SV - System value changed, except for QAUDCTL severity 2 case
    • ZC - Object accessed (change)
    • ZR - Object accessed (read)
The Common Event Format key names that are generated within the SYSLOG_EVENT column are:
Table 2. Common Event Format key names
Common Event Format key name Description
deviceExternalId Device name (extracted from ENTRY_DATA column)
dloName Document Library Object name (DLO_NAME column)
dloPath Document Library Object folder path (FOLDER_PATH column)
dproc Destination job (process) name (extracted from ENTRY_DATA column)
duser Destination user name (extracted from ENTRY_DATA column)
filePath IFS stream file path (PATH_NAME column)
fileType Object type (OBJECT_TYPE column)
fname IFS stream file name (OBJECT_FILE_NAME column)
msg Additional information from the audit record not included in other keys (extracted from ENTRY_DATA column)
objName Object name (OBJECT column)
oldDloName Document Library Object name (before rename) (extracted from ENTRY_DATA column)
oldDloPath Document Library Object folder path (before rename) (extracted from ENTRY_DATA column)
oldFileName IFS stream file name (before rename) (extracted from ENTRY_DATA column)
oldFilePath IFS stream file path (before rename) (extracted from ENTRY_DATA column)
oldObjName Object name (before rename) (extracted from ENTRY_DATA column)
reason Text description of the audit journal entry
shost Source system (host) name (SYSTEM_NAME column)
sproc Source job (process) name (JOB_NAME, JOB_USER, JOB_NUMBER columns)
spt Source port number (REMOTE_PORT column)
src Source IP address (REMOTE_ADDRESS column)
suser Source user name (CURRENT_USER column)

Examples

  • Select all entries from the *CURRENT receiver of journal TESTLIB/QSQJRN.
    SELECT * FROM TABLE (
                 DISPLAY_JOURNAL( 'TESTLIB', 'QSQJRN')) AS JT;
  • Find all changes made by SUPERUSER against the PRODDATA/SALES table. The first two arguments are passed without names since they correspond with the first two parameters for the function. The other four arguments are passed using the parameter name syntax to avoid specifying a value for the parameters that are not needed.
    SELECT journal_code, journal_entry_type, object, object_type, X.* 
FROM TABLE (
  QSYS2.Display_Journal(
            'PRODDATA', 'QSQJRN', -- Journal library and name
            OBJECT_LIBRARY=>'PRODDATA', OBJECT_NAME=>'SALES',
            OBJECT_OBJTYPE=>'*FILE', OBJECT_MEMBER=>'SALES' 
    ) ) AS X
WHERE journal_entry_type in ('DL', 'PT', 'PX', 'UP') AND "CURRENT_USER" = 'SUPERUSER'
ORDER BY entry_timestamp DESC
  • Select entries from the audit journal that return syslog information and format them with an RFC5424 header.
    SELECT syslog_facility, syslog_severity, syslog_event  
  FROM TABLE (QSYS2.DISPLAY_JOURNAL('QSYS', 'QAUDJRN',
                                    GENERATE_SYSLOG =>'RFC5424'
              ) ) AS X
  WHERE syslog_event IS NOT NULL;