Retrieve Journal Entries (QjoRetrieveJournalEntries) API

The Retrieve Journal Entries (QjoRetrieveJournalEntries) API provides access to journal entries. The journal entry information available is similar to what is provided by using the Display Journal (DSPJRN), Receive Journal Entry (RCVJRNE), and Retrieve Journal Entry (RTVJRNE) CL commands. Additionally, journal entry data that cannot be retrieved through these CL interfaces because of length or structure is available through this API as pointers to the additional data.

See the Journal management topic for more information about journaling and the various types of journal entries that are available for retrieval.

Note: Under certain conditions, even if an error message is returned to this API, a partial list of journal entries may be retrieved into the receiver variable. If you receive error messages CPF3CF1, CPF3C90, CPF6948, CPF6949 or CPF9872, then the receiver variable has not yet been modified. For all other error messages, a non-zero value for bytes returned indicates journal entry information may be available and the number of entries retrieved field will reflect how many entries are being returned prior to receiving the error message.

Restrictions

• If the sequence number is reset in the range of the receivers specified, the first occurrence of starting sequence number or ending sequence number is used if these key fields are specified.
• The job, program, and user profile keys cannot be used to specify selection criteria if one or more journal receivers in the specified receiver range was attached to a journal that had a RCVSIZOPT or FIXLENDTA option specified that omitted the collection of that data.
• The file, object, object path, object file identifier, directory subtree, name pattern, journal code, entry type, job, program, user profile, commit cycle identifier, and dependent entries keys can be used to specify a subset of all available entries within a range of journal entries.
  • If no values are specified using these keys, all available journal entries are retrieved.
  • If more than one of these keys are specified, then a journal entry must satisfy all of the values specified on these keys, except when ignore file selection (*IGNFILSLT) or ignore object selection (*IGNOBJSLT) is specified on the journal code key.
  • If a journal code is specified on the journal code key and *IGNFILSLT is the second element of that journal code, then journal entries with the specified journal code are selected if they satisfy all selection criteria except what is specified on the file key.
  • If a journal code is specified on the journal code key and *IGNOBJSLT is the second element of that journal code, then journal entries with the specified journal code are selected if they satisfy all selection criteria except what is specified on the object, object path, object file identifier, directory subtree, and name pattern keys.
• If more than the maximum number of objects is identified ( 32767 objects), an error occurs and no entries are converted for output. This restriction is ignored if *ALLFILE is specified or no objects are specified. All journal entries are retrieved, regardless of which objects, if any, the entries are associated with.

Authorities and Locks

Journal Authority

*USE

Journal Library Authority

*EXECUTE

Journal Receivers Authority

*USE

Journal Receivers Library's Authority

*EXECUTE

Non-Integrated File System Object Authority (if specified)

*USE

Non-Integrated File System Object Library Authority

*EXECUTE

Integrated File System Object Authority (if specified)

*R (also *X if object is a directory and *ALL is specified for the directory subtree key)

Directory Authority (for each directory preceding the last component in the path name)

*X

Journal Lock

*SHRRD

Journal Receiver Lock

*SHRRD

Non-Integrated File System Object Lock (if specified)

*SHRRD

Integrated File System Object Lock (if specified)

O_RDONLY | O_SHARE_RDWR

*OBJEXIST is also required for the journal authority if any of the the following are true:

• *ALLFILE has been specified for the file key or no objects were specified
• Specified object does not exist on the system
• *IGNFILSLT or *IGNOBJSLT is specified for the journal code selection value for any selected journal codes
• The journal is a remote journal

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that receives the entries requested. You can specify the size of the area smaller than the format requested as long as you specify the length of receiver variable parameter correctly. As a result, the API returns only the data the area can hold. Only complete journal entries will be returned.

Note: This receiver variable must be aligned on a 16-byte boundary since the journal entry specific data could include actual pointers.

If the receiver variable was not large enough to hold the retrieved journal entries, the API can be called again, specifying the same selection criteria and specifying a starting sequence number one greater than the last sequence number returned.

Length of receiver variable

INPUT; BINARY(4)

The length of receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. If the length of receiver variable parameter specified is smaller than the journal entry to be returned, no journal entry will be returned and no error will be signalled. The minimum length is 13 bytes.

Qualified journal name

INPUT; CHAR(20)

The name of the journal and its library from which the journal entries are to be retrieved. The first 10 characters contain the journal name. The second 10 characters contain the library name. The special values supported for the library name follow:

*LIBL	Library list
*CURLIB	Current library

Format name

INPUT; CHAR(8)

The formats RJNE0100 and RJNE0200 are the only supported formats that are used by this API. For more information, see the RJNE0100 Format and the RJNE0200 Format.

Omissible Parameter Group

Journal entries to retrieve

INPUT; CHAR(*)

The selection criteria, if any, to use for the journal entries to be retrieved from the journal. If this parameter is not specified, all journal entries in the currently attached journal receiver that fit in the length of receiver variable parameter will be retrieved. Only complete journal entries will be returned. The information must be in the following format:

Number of variable length records

BINARY(4)

The total number of all of the variable length records. If this field is zero, no variable length records are processed, and no key information will be retrieved.

Variable length records

CHAR(*)

The types of entries that should be retrieved. For the specific format of the variable length record, see Format for Variable Length Record.

Note: This receiver variable must be aligned on a 16-byte boundary since the journal entry specific data could include actual pointers.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Format for Variable Length Record

The following table defines the format for the variable length records.

If you specify a length of data that is longer than the key field's required data length, the data will be truncated at the right. No error message will be returned.

If you specify a length of data that is shorter than the key field's required data length, an error message will be returned.

You may specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.

Each variable length record must be 4-byte aligned. If not, unpredictable results may occur. If any keys are specified which include pointers, e.g. Object Path or Name Pattern, it is recommended that the length of each variable length record be a mulitple of 16 bytes. If not, errors may occur.

Field Descriptions

Data. The data that is used to determine how the journal entries should be retrieved. All values are validity checked.

Key. Identifies specific entries to be retrieved from the journal. See Keys for the list of valid keys.

Length of data. The length of the key information.

Length of variable length record. The length of the variable length record. This field is used to get the addressability of the next variable length record.

Keys

The following table lists the valid keys for the key field area of the variable length record. For detailed descriptions of the keys, see the Field Descriptions.

Some messages for this API refer to parameters and values of the Receive Journal Entry (RCVJRNE) command. This table also can be used to locate the key names that correspond to the RCVJRNE command parameters.

Key	Input Type	Field	RCVJRNE Command Parameter
1	CHAR(40)	Range of journal receivers	RCVRNG
2	CHAR(20)	Starting sequence number	FROMENT
3	CHAR(26)	Starting time stamp	FROMTIME
4	CHAR(20)	Ending sequence number	TOENT
5	CHAR(26)	Ending time stamp	TOTIME
6	BINARY(4)	Number of entries	NBRENT
7	CHAR(*)	Journal codes	JRNCDE
8	CHAR(*)	Journal entry types	ENTTYP
9	CHAR(26)	Job	JOB
10	CHAR(10)	Program	PGM
11	CHAR(10)	User profile	USRPRF
12	CHAR(20)	Commit cycle identifier	CMTCYCID
13	CHAR(10)	Dependent entries	DEPENT
14	CHAR(10)	Include entries	INCENT
15	CHAR(10)	Null value indicators length	NULLINDLEN
16	CHAR(*)	File	FILE
17	CHAR(*)	Object	OBJ
18	CHAR(*)	Object path	OBJPATH
19	CHAR(*)	Object file identifier	OBJFID
20	CHAR(5)	Directory subtree	SUBTREE
21	CHAR(*)	Name pattern	PATTERN
22	CHAR(10)	Format Minimized Data	FMTMINDTA

Field Descriptions

Commit cycle identifier. The commit cycle identifier of the specific journal that participated in a logical unit of work for which the journal entries are to be retrieved. This Char(20) field is treated as Zoned(20,0) except when the special value *ALL is specified. The default is *ALL. The possible values are:

Dependent entries Whether the journal entries to be retrieved include the journal entries recording actions

• that occur as a result of a trigger program.
• on records that are part of a referential constraint.
• that will be ignored during an apply journaled changes (APYJRNCHG) or remove journaled changes (RMVJRNCHG) operation.

The default is *ALL. The possible values are:

Directory subtree. Whether the directory subtrees are included in the retrieve operation. The default is *NONE.

Note: This key is ignored if Key 18 (object path) is not specified or if the object is not a directory.

Ending sequence number. The last journal entry considered for retrieval. This Char(20) field is treated as Zoned(20,0) except when the special value *LAST is specified. The default is *LAST. The possible values are:

Note: If this key is specified, Key 5 (ending time stamp) cannot also be specified.

Ending time stamp. The time stamp of the last journal entry considered for retrieval. This Char(26) field is in the format YYYY-MM-DD-HH.MM.SS.UUUUUU where

Notes:

1. If this key is specified, Key 4 (ending sequence number) cannot also be specified.
   
   
2. If the system value QLEAPADJ (Leap year adjustment) is zero, then the result returned will be in 1 microsecond granularity. If the system value QLEAPADJ is greater than zero, then the result returned will be in 8 microsecond granularity.

File. A list of files and members for which journal entries are to be retrieved. For the format of this field, see File Format. If *ALLFILE is specified for the file name, the list cannot contain other entries.

To determine which journal entries are to be retrieved, based on the specified file member name, the following is done:

• If the journal is a local journal, and if the specified file member currently exists on the system, the journal identifier is determined from the specified file member. All journal entries in the specified receiver range for that journal identifier are retrieved.
• If the journal is a remote journal, or if the specified file member does not currently exist on the system, the specified receiver range is searched to determine all possible journal identifiers that are associated with the specified file member. All journal entries in the specified receiver range for those journal identifiers are retrieved. Specify the library name or *CURLIB to have entries returned for a file.

  There may be more than one journal identifier associated with a specified object within the specified receiver range. This can happen when a journaled object is deleted, and then a new object is created with the same name and journaled to the same journal.

1. The journal identifier is the unique identifier associated with the object when journaling is started for that object. The journal identifier stays constant, even if the object is renamed, moved or restored. See the Journal management topic for more information.
   
   
2. When specifying a database file on this key, journal entries with the following journal code values are retrieved only if they satisfy the values specified on the other keys:
   • Journal code D (database file-level information entries).
   • Journal code F (file member-level information entries).
   • Journal code R (record-level information entries).
   • Journal code U (user-generated entries).
   • Other journal codes if *IGNFILSLT is the second element of the journal code key. If *ALLSLT is the second element of the journal code key, no journal entries with that code are retrieved.
   
   
3. Either Key 16 (file) may be specified, or one or more of the object keys, Key 17 (object), Key 18 (object path), or Key 19 (object file identifier) may be specified, but not both.
   

Format minimized data. Specifies whether entry specific data which has been minimized on field boundaries will be returned in a readable format. The default is *NO. The possible values are:

Include entries. Whether only the confirmed or both the confirmed and unconfirmed journal entries are retrieved. This key only applies when retrieving journal entries from a remote journal. The default is *CONFIRMED.

Confirmed entries are those journal entries that have been sent to this remote journal, and the state of the input/output (I/O) to auxiliary storage for the same journal entries on the local journal is known.

Unconfirmed entries can occur for two reasons. First, the journal entries have been sent to the remote journal, but the state of the input/output (I/O) to auxiliary storage for the same journal entries on the local journal is not yet known. If the connection to the source system is lost, these entries will be deleted from the remote system and will never become confirmed. This situation only occurs if synchronous delivery mode is being used for the remote journal. Secondly, unconfirmed entries may exist because the object name information for those journal entries is not yet known to the remote journal. Even if the connection to the source system is lost, these entries will eventually become confirmed. This situation can occur for either synchronous or asynchronous delivery mode to a remote journal.

The possible values are:

Job. Whether the journal entries being retrieved are limited to the journal entries for a specified job. Only journal entries for the specified job are considered for retrieval. The default is *ALL. The possible values are:

Journal codes. A list of journal codes for which entries are to be retrieved. For the format of this field, see Journal Code Format. If *ALL or *CTL is specified for the journal code value, the list cannot contain other entries and the journal code selection field must be blank. The default is *ALL for the journal code value.

Journal entry types. A list of journal entry types for which entries are to be retrieved. For the format of this field, see Journal Entry Type Format. If *ALL or *RCD is specified for the journal entry type, the list cannot contain other entries. The default is *ALL for the journal entry type.

Name pattern. The patterns to be used to include or omit objects for which journal entries are to be retrieved. The default will be to include all patterns that match. For the format of this field, see Name Pattern Format.

Notes:

1. This key is ignored if Key 18 (object path) is not specified.
   
   
2. The sum of the lengths of all the variable length records that precede this key must be a multiple of 16 bytes. If not, errors will occur. For ease of implementation, it is recommended that the length of each variable length record be a mulitple of 16 bytes.
   

Null value indicators length. The length, in bytes, used for the null value indicators portion of the journal entry retrieved by the user. This Char(10) field is treated as Zoned(10,0) except when the special value *VARLEN is specified. The default is *VARLEN. The possible values are:

If the journal entry being retrieved has fewer null value indicators than the length specified, the trailing bytes are set to 'F0'X. Conversely, if a journal entry retrieved has more null value indicators than the specified field length and truncation will result in the loss of a significant null value indicator (either a 'F1'X or a 'F9'X), the request is ended.

Number of entries. The maximum number of journal entries that are requested to be retrieved. Less than this maximum could be retrieved if fewer entries meet all the other selection criteria or if there is not enough space for all the requested entries.

Object. A list of objects for which journal entries are to be retrieved. For the format of this field, see Object Format. Only objects of type *DTAARA, *DTAQ, and *FILE are supported.

To determine which journal entries are to be retrieved, based on the specified object name, the following is done:

• If the journal is a local journal, and if the specified object currently exists on the system, the journal identifier is determined from the specified object. All journal entries in the specified receiver range for that journal identifier are retrieved.
• If the journal is a remote journal, or if the specified object does not currently exist on the system, the specified receiver range is searched to determine all possible journal identifiers that are associated with the specified object. All journal entries in the specified receiver range for those journal identifiers are retrieved. Specify the library name or *CURLIB to have entries returned for an object.

  There may be more than one journal identifier associated with a specified object within the specified receiver range. This can happen when a journaled object is deleted, and then a new object is created with the same name and journaled to the same journal.

1. The journal identifier is the unique identifier associated with the object when journaling is started for that object. The journal identifier stays constant, even if the object is renamed, moved or restored. See the Journal management topic for more information.
   
   
2. When specifying an object on this key, journal entries with the following journal code values are retrieved only if they satisfy the values specified on the other keys:
   • Journal code D (database file-level information entries).
   • Journal code E (data area information entries).
   • Journal code F (file member-level information entries).
   • Journal code R (record-level information entries).
   • Journal code Q (data queue information entries).
   • Journal code U (user-generated entries).
   • Other journal codes if *IGNOBJSLT is the second element of the journal code key. If *ALLSLT is the second element of the journal code key, no journal entries with that code are retrieved.
   
   
3. Either Key 16 (file) may be specified, or one or more of the object keys, Key 17 (object), Key 18 (object path), or Key 19 (object file identifier) may be specified, but not both.

Object file identifier. A list of file identifiers (FIDs) for which journal entries are to be retrieved. FIDs are unique identifiers associated with integrated file system objects. Only objects whose FID identifies an object of type *STMF, *DIR, or *SYMLNK that is in the "root" ('/'), QOpenSys, and user-defined file systems are supported. All other objects are ignored. For the format of this field, see Object File Identifier Format.

To determine which journal entries are to be retrieved, based on the specified file identifier, the following is done:

• If the journal is a local journal, and if the specified object currently exists on the system, the journal identifier is determined from the specified object. All journal entries in the specified receiver range for that journal identifier are retrieved.
• If the journal is a remote journal, or if the specified object does not currently exist on the system, the specified receiver range is searched to determine all possible journal identifiers that are associated with the specified object. All journal entries in the specified receiver range for those journal identifiers are retrieved.

1. The journal identifier is the unique identifier associated with the object when journaling is started for that object. The journal identifier stays constant, even if the object is renamed, moved or restored. See the Journal management topic for more information.
   
   
2. When specifying an object on this key, journal entries with the following journal code values are retrieved only if they satisfy the values specified on the other keys:
   • Journal code B (integrated file system information entries).
   • Journal code U (user-generated entries).
   • Other journal codes if *IGNOBJSLT is the second element of the journal code key. If *ALLSLT is the second element of the journal code key, no journal entries with that code are retrieved.
   
   
3. Either Key 16 (file) may be specified, or one or more of the object keys, Key 17 (object), Key 18 (object path), or Key 19 (object file identifier) may be specified, but not both.

Object path. A list of integrated file system objects, entered via path name, for which journal entries are to be retrieved. Only objects of type *STMF, *DIR, or *SYMLNK that are in the "root" ('/'), QOpenSys, and user-defined file systems are supported. All other objects are ignored. For the format of this field, see Object Path Format.

Only objects that are currently linked with the specified path name and have a journal identifier associated with them are used in journal entry selection. If the specified object does exist, the journal identifier associated with that link is used for journal entry selection. If a specified object does not exist or does not have a journal identifier associated with it, that link is not used in selecting journal entries and no error is sent.

1. The sum of the lengths of all the variable length records that precede this key must be a multiple of 16 bytes. If not, errors will occur. For ease of implementation, it is recommended that the length of each variable length record be a mulitple of 16 bytes.
   
   
2. The journal identifier is the unique identifier associated with the object when journaling is started for that object. The journal identifier stays constant, even if the object is renamed, moved or restored. See the Journal management topic for more information.
   
   
3. When specifying an object on this key, journal entries with the following journal code values are retrieved only if they satisfy the values specified on the other keys:
   • Journal code B (integrated file system information entries).
   • Journal code U (user-generated entries).
   • Other journal codes if *IGNOBJSLT is the second element of the journal code key. If *ALLSLT is the second element of the journal code key, no journal entries with that code are retrieved.
   
   
4. Either Key 16 (file) may be specified, or one or more of the object keys, Key 17 (object), Key 18 (object path), or Key 19 (object file identifier) may be specified, but not both.

Program. Whether the journal entries being retrieved are limited to the journal entries for a specified program. Only journal entries for the specified program name are considered for retrieval. The default is *ALL. The possible values are:

Range of journal receivers. The qualified names of the starting (first) and ending (last) journal receivers used in the search for a journal entry to be retrieved. For the format of this field, see Receiver Range Format. The system starts the search with the starting journal receiver and proceeds through the receiver chain until the ending journal receiver is processed.

If *CURCHAIN or *CURRENT is specified for the starting journal receiver, the remaining fields should be set to blanks. The default is *CURRENT for the starting journal receiver. If the total number of receivers in the range is larger than 2045, an error message is sent and no journal entry is retrieved.

Starting sequence number. The first journal entry considered for retrieval. This Char(20) field is treated as Zoned(20,0) except when the special value *FIRST is specified. The default is *FIRST. The possible values are:

Note: If this key is specified, Key 3 (starting time stamp) cannot also be specified.

Starting time stamp. The time stamp of the first journal entry considered for retrieval. This Char(26) field is in the format YYYY-MM-DD-HH.MM.SS.UUUUUU where

1. If this key is specified, Key 2 (starting sequence number) cannot also be specified.
   
   
2. Note: If the system value QLEAPADJ (Leap year adjustment) is zero, then the result returned will be in 1 microsecond granularity. If the system value QLEAPADJ is greater than zero, then the result returned will be in 8 microsecond granularity.

User profile. Whether the journal entries being retrieved are limited to the journal entries for a specified user profile name. The user profile name is the user profile under which the job is run that deposited the journal entries. Only journal entries for the specified user profile are considered for retrieval. The default is *ALL. The possible values are:

File Format

Field Descriptions

File name. The file name for which journal entries are to be retrieved. The possible values are:

Library name. The library name associated with the file name for which journal entries are to be retrieved. The possible values are:

Member name. The file member name for which journal entries are to be retrieved. The possible values are:

*FIRST	Entries for the database file and the first member in the file are retrieved.
*ALL	Entries for the database file and all the currently existing members of the file are retrieved.
*NONE	Only entries for the database file are retrieved. Entries for members of the file are not retrieved.
member name	The name of the file member for which entries are retrieved. If the specified physical file does not exist on the system, specify either *ALL or a specific file member name. If *ALL is specified for the file name, this member name is used for all applicable files in the library.
blank	The member name field must be blank if *ALLFILE is specified for the file name.

Number in array. The number of file codes that are specified for this key. The possible values are 1 through 300. The value must be 1 if *ALLFILE or *ALL is specified for file name.

Journal Code Format

Field Descriptions

Journal code value. The journal code for which journal entries are to be retrieved. The possible values are:

Journal code selection. Whether other selection criteria apply to this specified journal code. The possible values are:

*ALLSLT	The journal entries with the specified journal code are to be retrieved only if all selection keys are satisfied.
*IGNFILSLT	The journal entries with the specified journal code are to be retrieved only if all selection keys except the file key are satisfied. Note: This value is not valid for journal codes D, F, and R. This value is not valid if Key 17 (object), Key 18 (object path), or Key 19 (object file identifier) is specified.
*IGNOBJSLT	The journal entries with the specified journal code are to be retrieved only if all selection keys are satisfied except the object, object path, object file identifier, directory subtree, and name pattern keys. Note: This value is not valid for journal codes B, D, E, F, Q, and R. This value is not valid if Key 16 (file) is specified.
blank	The journal code selection must be blank if *ALL or *CTL is specified for the journal code value.

Number in array. The number of journal codes that are specified for this key. The possible values are 1 through 16. The value must be 1 if *ALL or *CTL is specified for the journal code value.

Journal Entry Type Format

Field Descriptions

Journal entry types. The journal entry types for which journal entries are to be retrieved. The possible values are:

Number in array. The number of journal entry types that are specified for this key. The possible values are 1 through 300. The value must be 1 if *ALL or *RCD is specified for journal entry type.

Name Pattern Format

Field Descriptions

Include or omit. Whether the name pattern is included or omitted from the retrieve operation.

Length of this pattern entry. The length of the current pattern entry that can be used as the displacement from the start of this pattern entry to the next pattern entry. The length must be a minimum of 32 bytes and must be a multiple of 16.

Number in array. The number of patterns that are specified for this key. The possible values are 1 through 20.

Pointer to pattern path structure. A pointer to a path structure.

This pointer must be 16-byte aligned. If not, unpredictable results may occur.

Additional information about path name patterns is in the Integrated file system information in the Files and file systems topic.

The pointer given points to a path name structure. If that path name structure contains a pointer, it must be 16-byte aligned. If not, unpredictable results may occur.

For more information on the pattern path name format, see Path name format.

Reserved. A reserved field that must be set to hexadecimal zeros.

Object Format

Field Descriptions

Library name. The library name associated with the object for which journal entries are to be retrieved. The possible values are:

Member name, if *FILE specified. The file member name for which journal entries are to be retrieved. If the specified object type was not *FILE, the member name is ignored. The possible values are:

Number in array. The number of object names that are specified for this key. The possible values are 1 through 300.

Object name. The object name for which journal entries are to be retrieved. The possible values are:

Object type. The object type associated with the object for which journal entries are to be retrieved. The possible values are:

Object File Identifier Format

Field Descriptions

File identifier. The file identifier of the object for which journal entries are to be retrieved.

Number in array. The number of file identifiers that are specified for this key. The possible values are 1 through 300.

Object Path Format

Field Descriptions

Include or omit. Whether names that match the path name should be included or omitted from the operation. Note that in determining whether a name matches a pattern, relative name patterns are always treated as relative to the current working directory.

Note: Key 20 (directory subtree) specifies whether the subtrees are included or omitted.

Length of this object path name entry. The length of the current object path name entry that can be used as the displacement from the start of this path name entry to the next path name entry. The length must be a minimum of 32 bytes and must be a multiple of 16.

Number in array. The number of object path names that are specified for this key. The possible values are 1 through 300.

Pointer to an object path name. A pointer to the object path name of the object for which journal entries are to be retrieved. All path names are relative to the current directory at the time of the call.

In the last component of the path name, an asterisk (*) or a question mark (?) can be used to search for patterns of names. The * tells the system to search for names that have any number of characters in the position of the * character. The ? tells the system to search for names that have a single character in the position of the ? character. Symbolic links within the path name will not be followed. If the path name begins with the tilde (~) character, then the path is assumed to be relative to the appropriate home directory.

Additional information about path name patterns is in the Integrated file system information in the Files and file systems topic.

The pointer given points to a path name structure. If that path name structure contains a pointer, it must be 16-byte aligned. If not, unpredictable results may occur.

For more information on the path name format, see Path name format.

Reserved. A reserved field that must be set to hexadecimal zeros.

Receiver Range Format

Field Descriptions

Ending journal receiver library. The ending journal receiver library for which journal entries are to be retrieved. The possible values are:

Ending journal receiver name. The ending journal receiver name for which journal entries are to be retrieved. The possible values are:

Starting journal receiver library. The starting journal receiver library for which journal entries are to be retrieved. The possible values are:

Starting journal receiver name. The starting journal receiver name for which journal entries are to be retrieved. The possible values are:

RJNE0100 Format

The structure of the information returned is determined by the specified format name. For detailed descriptions of the fields, see Field Descriptions. The retrieved data is composed of four different sections as follows:

• A header section. Only one header section is returned per call. See Header.
• Journal entry sections. These three sections will be repeated for each journal entry retrieved.
  • Header section of journal entry. See This journal entry's header with format RJNE0100.
  • Null value indicators section of journal entry. This section will be one of the two following formats, depending on what was specified for the null value indicators key.
    
    
    • If the user did not specify the null value indicators key or specified null value indicators length(*VARLEN), see This journal entry's null value indicators if Null Value Indicators (*VARLEN) specified.
    • If the user specified null value indicators length(field length), see This journal entry's null value indicators if Null Value Indicators (field length) specified.

      Note: If a null value indicators length of 0 was specified, then this section will not appear in the journal entry data.

    
    
    
  • Entry specific data section of journal entry. See This journal entry's entry specific data.

Header

This journal entry's header with format RJNE0100

This journal entry's null value indicators if Null Value Indicators (*VARLEN) specified

This journal entry's null value indicators if Null Value Indicators (field length) specified

This journal entry's entry specific data

RJNE0200 Format

The structure of the information returned is determined by the specified format name. For detailed descriptions of the fields, see Field Descriptions. The retrieved data is composed as follows:

• A header section. Only one header section is returned per call. See Header.
• Journal entry sections. These optional sections will be repeated for each journal entry retrieved.
  • Header section of journal entry. See This journal entry's header with format RJNE0200.
  • Transaction identifier section of journal entry if the displacement to transaction identifier is not 0. See the QSYSINC/H.XA header file for the layout of this data.
  • Logical unit of work section of journal entry if the displacement to logical unit of work is not 0. See This journal entry's Logical unit of work if the displacement to logical unit of work is not 0.
  • Receiver information section of journal entry if the displacement to receiver information is not 0. See This journal entry's receiver information if the displacement to receiver information is not 0.
  • Null value indicators section of journal entry if the displacement to null values indicators is not 0. This section will be one of the two following formats, depending on what was specified for the null value indicators key
    • If the user did not specify the null value indicators key or specified null value indicators length(*VARLEN), see This journal entry's null value indicators if Null Value Indicators (*VARLEN) specified.
    • If the user specified null value indicators length(field length), see This journal entry's null value indicators if Null Value Indicators (field length) specified.

      Note: If a null value indicators length of 0 was specified, then this section will not appear in the journal entry data.

  • Entry specific data section of journal entry if the displacement to entry specific data is not 0. See This journal entry's entry specific data.

Header

This journal entry's header with format RJNE0200

Offset		Type	Field
Dec	Hex
0	0	BINARY(4), UNSIGNED	Displacement to next journal entry's header
4	4	BINARY(4), UNSIGNED	Displacement to this journal entry's null value indicators
8	8	BINARY(4), UNSIGNED	Displacement to this journal entry's entry specific data
12	C	BINARY(4), UNSIGNED	Displacement to this journal entry's transaction identifier
16	10	BINARY(4), UNSIGNED	Displacement to this journal entry's logical unit of work
20	14	BINARY(4), UNSIGNED	Displacement to this journal entry's receiver information
24	18	BINARY(8), UNSIGNED	Sequence number
32	20	BINARY(8), UNSIGNED	Unformatted Time stamp
40	28	BINARY(8), UNSIGNED	Thread identifier
48	30	BINARY(8), UNSIGNED	System sequence number
56	38	BINARY(8), UNSIGNED	Count/relative record number
64	40	BINARY(8), UNSIGNED	Commit cycle indentifier
72	48	BINARY(4), UNSIGNED	Pointer handle
76	4C	BINARY(2), UNSIGNED	Remote port
78	4E	BINARY(2), UNSIGNED	Arm number
80	50	BINARY(2), UNSIGNED	Program library ASP number
82	52	CHAR(16)	Remote Address
98	62	CHAR(1)	Journal code
99	63	CHAR(2)	Entry type
101	65	CHAR(10)	Job name
111	6F	CHAR(10)	User name
121	79	CHAR(6)	Job number
127	7F	CHAR(10)	Program name
137	89	CHAR(10)	Program library name
147	93	CHAR(10)	Program library ASP device name
157	9D	CHAR(30)	Object
187	BB	CHAR(10)	User profile
197	C5	CHAR(10)	Journal identifier
207	CF	CHAR(1)	Address family
208	D0	CHAR(8)	System name
216	D8	CHAR(1)	Indicator flag
217	D9	CHAR(1)	Object name indicator
218(0)	DA(0)	BIT(1)	Referential constraint
218(1)	DA(1)	BIT(1)	Trigger
218(2)	DA(2)	BIT(1)	Incomplete data
218(3)	DA(3)	BIT(1)	Ignored during APYJRNCHG or RMVJRNCHG
218(4)	DA(4)	BIT(1)	Minimized entry specific data
218(5)	DA(5)	BIT(1)	File type indicator
218(6)	DA(6)	BIT(1)	Minimized on field boundaries
218(7)	DA(7)	BIT(1)	Reserved
219	DB	CHAR(10)	Object type
229	E5	CHAR(3)	Reserved
229	E8	BINARY(4), UNSIGNED	Nested commit level

This journal entry's Logical unit of work if the displacement to logical unit of work is not 0

This journal entry's receiver information if the displacement to receiver information is not 0

Field Descriptions

Address family. The address family identifies the format of the remote address for this journal entry. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*RMTADR) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then 0 will be returned for the address family.

0	This entry was not associated with any remote address.
4	The format of the remote address is internet protocol version 4. The remote address is returned as a 16-byte character field.
6	The format of the remote address is internet protocol version 6. The remote address is returned as a 128-bit binary number.

Arm number. The number of the disk arm that contains the journal entry.

Bytes returned. The number of bytes of data returned.

If an error message is returned, other than error messages CPF3CF1, CPF3C90, CPF6948, CPF6949 or CPF9872, this field should be checked to determine if partial journal entry information has been returned.

Commit cycle identifier. A number that identifies the commit cycle. This is either a Char(20) or Binary(8) field and if Char(20), it is treated as Zoned(20,0). A commit cycle is from one commit or rollback operation to another.

The commit cycle identifier is found in every journal entry that is associated with a commitment transaction. If the journal entry was not made as part of a commitment transaction, this field is zero.

Continuation handle. An indicator for more journal entries available that meet any specified selection criteria. The possible values are:

Note: If an error message was returned and partial journal entry information was returned, this field may not correctly indicate whether additional journal entries are available.

Continuation indicator. An indicator for more journal entries available that meet the specified selection criteria. The possible values are:

Note: If an error message was returned and partial journal entry information was returned, this field may not correctly indicate whether additional journal entries are available.

Continuation starting receiver library. When the continuation indicator is 1, then this field will identify the name of the library that contains the receiver that holds the next journal entry that could be retrieved with the same selection criteria on a subsequent call to this API. When used in conjunction with the continuation starting receiver name and the continuation starting sequence number, a subsequent API call will ensure that no journal entries in the given receiver range will be skipped, irrespective of any reset of sequence numbers that may have taken place within the given receiver range. When the continuation indicator is 0, then this field will be blanks.

Continuation starting receiver. When the continuation indicator is 1, then this field will identify the name of the receiver that holds the next journal entry that could be retrieved with the same selection criteria on a subsequent call to this API. When used in conjunction with the continuation starting receiver library name and the continuation starting sequence number, a subsequent API call will ensure that no journal entries in the given receiver range will be skipped, irrespective of any reset of sequence numbers that may have taken place within that receiver range. When the continuation indicator is 0, then this field will be blanks.

Continuation starting sequence number. When the continuation indicator is 1, then this field will identify the sequence number of the next journal entry that could be retrieved with the same selection criteria on a subsequent call to this API. When used in conjunction with the continuation starting receiver library name and the continuation starting receiver name, a subsequent API call will ensure that no journal entries in the given receiver range will be skipped, irrespective of any reset of sequence numbers that may have taken place within that receiver range. When the continuation indicator is 0, then this field will be blanks. This is a Char(20) field that is treated as Zoned(20,0).

Count/relative record number. 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. See the Journal Entry Information appendix in the Journal management topic to see specific values for this field, if applicable. This is either a Char(10) or a unsigned Binary(8) field and if Char(10), it is treated as Zoned(10,0).

Displacement to next journal entry's header. The displacement from the start of this journal entry's header section to the start of the journal entry header section for the next journal entry.

Displacement to this journal entry's entry specific data. The displacement from the start of this journal entry's header section to the start of the entry specific data section for this journal entry. A value of 0 indicates that this data is not returned for this journal entry.

Displacement to this journal entry's logical unit of work. The displacement from the start of this journal entry's header section to the start of the logical unit of work section for this journal entry. A value of 0 indicates that this data is not returned for this journal entry.

Displacement to this journal entry's receiver information. The displacement from the start of this journal entry's header section to the start of the receiver information section for this journal entry. A value of 0 indicates that this data is not returned for this journal entry. Journal receiver information is returned only for the first entry in a buffer and when the receiver information changes from one journal entry to the next. If no journal receiver information is returned, it can be assumed that the receiver information from the previous entry will apply to the current journal entry.

Displacement to this journal entry's null value indicators. The displacement from the start of this journal entry's header section to the start of the null value indicators section for this journal entry. A value of 0 indicates that this data is not returned for this journal entry.

Displacement to this journal entry's transaction identifier. The displacement from the start of this journal entry's header section to the start of the transaction identifier section for this journal entry. A value of 0 indicates that this data is not returned for this journal entry.

Entry specific data. The entry specific data returned for this journal entry. See the Journal management topic for the layouts of this information for each journal entry type.

If the incomplete data indicator is on, then this data contains pointers to additional journal entry data. See Use of Pointers within Entry Specific Data for a discussion on the use of these pointers.

Entry type. Further identifies the type of user-created or system-created entry. See the Journal Entry Information in the Journal management topic for descriptions of the entry types.

Entry type. Further identifies the type of user-created or system-created entry. See the Journal Entry Information in the Journal management topic for descriptions of the entry types.

File type indicator. Identifies whether or not this journal entry is associated with a logical file. The value will be 0 if the value for object type is not *FILE. The possible values are:

Ignore during APYJRNCHG or RMVJRNCHG. Whether this entry is ignored during a Apply Journaled Changes (APYJRNCHG) or Remove Journaled Changed (RMVJRNCHG) command. The possible values are:

Incomplete data. Whether this entry has data that must be additionally retrieved using a pointer returned for the missing information. See Use of Pointers within Entry Specific Data for more information. The possible values are:

Indicator flag. An indicator for the operation. See the Journal Entry Information appendix in the Journal management topic to see specific values for this field, if applicable.

Job name. The name of the job that added the entry.

Notes:

1. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*JOB) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then *OMITTED is returned for the job name.
2. If the journal entry was deposited by a system task that was not associated with a job, then *TDE will be returned for the job name.
3. If the job name was not available when the journal entry was deposited, then *NONE is returned for the job name.

Job number. The job number of the job that added the entry.

Notes:

1. If the RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*JOB) was not was in effect for the journal when the journal receiver that contains the journal entry was attached, then zeros are returned for the job number.
2. If the journal entry was deposited by a system task that was not associated with a job, then zeros will be returned for the job number.
3. If the job name was not available when the journal entry was deposited, then zeros are returned for the job number.

Journal code. The primary category of the journal entry. See the Journal Entry Information section in the Journal management topic for descriptions of the journal codes.

Journal identifier. The journal identifier (JID) for the object. When journaling is started for an object, the system assigns a unique JID to that object. The JID remains constant even if the object is renamed or moved. If journaling is stopped, however, there is no guarantee that the JID will be the same when journaling is started again for the same object.

If no JID is associated with the entry, this field has hexadecimal zeros.

Length of entry specific data. The length of the entry specific data returned for this journal entry. This Char(5) field is treated as Zoned(5,0). If the entry specific data includes any pointers to additional data, the length of that additional data in not included in this value. See Use of Pointers within Entry Specific Data for more information.

Length of null value indicators. The length of the null value indicators returned for this journal entry.

Logical unit of work. The logical unit of work identifies entries to be associated with a given unit of work, usually within a commit cycle. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*LUW) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then no logical unit of work will be returned for this entry and the displacement to this entry's logical unit of work will be 0.

Minimized entry specific data. Whether this entry has minimized entry specific data as a result of the journal having specified MINENTDTA for the object type of the entry. The possible values are:

Minimized on field boundaries. Whether this entry has minimized entry specific data on field boundaries as a result of the journal having been specified with MINENTDTA(*FLDBDY). The possible values are:

Nested commit level. Indicates the nesting level of the commit cycle that was open when a journal entry representing an object level change was deposited. The primary commit cycle is considered the first level of nesting and subsequent save point entries that were deposited prior to this entry correspond to additional levels of nesting. This field will be zero if any of the following are true:

• This journal entry does not represent an object level change (object level changes are the result of using commands like: CRTPF, CHGPF, MOVOBJ, and RNMOBJ).
• This journal entry was not deposited under commitment control.
• This journal entry was deposited on a release prior to V5R4M0.

Null value indicators. The null value indicators returned for this journal entry. If the record image has not been minimized or has been minimized on field boundaries in the entry specific data, then there is one null value indicator for each field in the physical file. Each indicator is one character long and has one of the following values:

Number of entries retrieved. The number of journal entries that were retrieved.

If an error message is returned, other than error messages CPF3CF1, CPF3C90, CPF6948, CPF6949 or CPF9872, a non-zero bytes returned field will reflect how much data was returned prior to the sending of the error message.

Object. The name of the object for which the journal entry was added. If the entry is not associated with a journaled object, this field is blank.

If the object associated with the journal entry is a file object the format of this field is:

Note: If the journal receiver was attached prior to installing V4R2M0 on your system, the following items are true:

• If *ALLFILE is specified for the file key, then the fully qualified name is the most recent name of the file when the newest receiver in the receiver range was the attached receiver and when the file was still being journaled.
• If a file name is specified or if library *ALL is specified on the file key, the current fully qualified name of the file appears in the retrieved journal entry.

If the journal receiver was attached while V4R2M0 or a later release was running on the system, the fully qualified name is the name of the object at the time the journal entry was deposited.

If the object associated with the journal entry is an integrated file system object, the format of this field is:

For all other entries associated with journaled objects, the format of this information is:

Object name indicator. An indicator with respect to the information in the object field. The valid values are:

Object type. The type of object in the entry. The possible values are:

Offset to first journal entry header. The offset from the start of the format to the journal entry header section for the first journal entry that is retrieved. If no entries are retrieved, this value is 0.

Pointer handle. If the entry specific data returned for this journal entry returned any pointers, this is the handle associated with those pointers. Otherwise, it is 0.

See Use of Pointers within Entry Specific Data for a discussion on the use of these pointers and what you must do with this pointer handle.

Program library ASP device name. The name of the ASP device that contains the program.

Notes:

1. If the program library ASP is not an independent ASP, then *SYSBAS will be returned for the program library ASP device name.
2. If the program library ASP device name was not available when the journal entry was deposited, or if RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*PGMLIB) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then *OMITTED is returned for the program library ASP device name.

Program library ASP number. The number for the auxiliary storage pool that contains the program that added the journal entry. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*PGMLIB) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then Hex 0 will be returned for program ASP number.

Program library name. The name of the library that contains the program that added the journal entry. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*PGMLIB) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then *OMITTED will be returned for the program library name.

Program name. The name of the program that added the entry. If an application or CL program did not add the entry, the field contains the name of a system-supplied program such as QCMD or QPGMMENU. If the program name is the special value *NONE, then one of the following is true:

• The program name does not apply to this journal entry.
• The program name was not available when the journal entry was made. For example, the program name is not available if the program was destroyed.

If the program that deposited the journal entry is an original program model program, this data will be complete. Otherwise, this data is unpredictable.

If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*PGM) was not in effect for the journal when the journal receiver that contains this journal entry was attached, *OMITTED is returned as the program name.

Receiver library ASP device name. The name of the ASP device that contains the receiver.

Notes:

1. If the receiver library ASP is not an independent ASP, then *SYSBAS will be returned for the receiver library ASP device name.
2. If the receiver library ASP device name was not available when the journal entry was deposited, then *OMITTED is returned for the receiver library ASP device name.

Receiver library ASP number. The number for the auxiliary storage pool containing the receiver holding the journal entry.

Receiver library name. The name of the library containing the receiver holding the journal entry.

Receiver name. The name of the receiver holding the journal entry.

Referential constraint. Whether this entry was recorded for actions that occurred on records that are part of a referential constraint.

Remote address. The remote address associated with the journal entry. The format of the address is dependent on the value of the address family for this journal entry. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*RMTADR) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then Hex 0 will be returned for remote address.

Remote port. The port number of the remote address associate with this journal entry. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*RMTADR) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then Hex 0 will be returned for remote port.

Reserved. Reserved area. It always contains hexadecimal zeros.

Sequence number. A number assigned by the system to each journal entry. This is either a Char(20) or Binary(8) field and if Char(20), it is treated as Zoned(20,0). It is initially set to 1 for each new or restored journal and is incremented until you request that it be reset when you attach a new receiver. There are occasional gaps in the sequence numbers because the system uses internal journal entries for control purposes. These gaps occur if you use commitment control, journal physical files, or journal access paths.

System name. The name of the system on which the entry is being retrieved, if the journal receiver was attached prior to installing V4R2M0 on the system. If the journal receiver was attached while the system was running V4R2M0 or a later release, the system name is the system where the journal entry was actually deposited.

System sequence number. The system sequence number indicates the relative sequence of when this journal entry was deposited into the journal. The system sequence number could be used to sequentially order journal entries that are in separate journal receivers. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*SYSSEQ) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then Hex 0 will be returned for the system sequence number.

Thread identifier. Identifies the thread within the process that added the journal entry. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*THD) was not in effect for the journal when the journal receiver that contains this journal entry was attached, then hex 0 will be returned for the thread identifier.

Time stamp. The system date and time when the journal entry was added to the journal receiver. The time stamp is in the format YYYY-MM-DD-HH.MM.SS.UUUUUU where

The system cannot assure that the time stamp is always in ascending order for sequential journal entries because the value of the system time could have been changed.

Note: If the system value QLEAPADJ (Leap year adjustment) is zero, then the result returned will be in 1 microsecond granularity. If the system value QLEAPADJ is greater than zero, then the result returned will be in 8 microsecond granularity.

Transaction identifier. The transaction identifier associated with this journal entry. The transaction identifier identifies transactions related to specific commit cycles. See the QSYSINC/H.XA header file for the layout of this data. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*XID) was not in effect for the journal when the journal receiver that contains the journal entry was attached, then the displacement to transaction identifier will be 0 and no transaction identifier will be returned.

Trigger. Whether this entry was created as result of a trigger program.

Unformatted time stamp. The system date and time when the journal entry was added to the journal receiver. The time stamp is in machine readable format and can be used as input to a time conversion API, which will convert it to a human readable format.

User name. The user profile name of the user that started the job.

Notes:

1. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*JOB) was not in effect for the journal when the journal receiver that contains the journal entry was attached, then blanks are returned for the user name.
2. If the job name was not available when the journal entry was deposited, then blanks are returned for the user name.

User profile. The name of the effective user profile under which the job was running when the entry was created.

Notes:

1. If RCVSIZOPT(*MINFIXLEN) was in effect or FIXLENDTA(*JOB) was not in effect for the journal when the journal receiver that contains this journal entry was attached, *OMITTED is returned for the effective user profile.
2. If the journal entry was deposited by a system task that was not associated with a job, then a character representation of the task description entry number will be returned for the user profile.

Use of Pointers within Entry Specific Data

There are some journal entries that require additional handling of the journal receiver entry specific data using pointers. This was done to minimize movement of large amounts of data and to facilitate support of tables or database files with large object (LOB) fields. The types of entries that may require pointer support are:

• Any operations on specific records or files (journal code R or F) of tables or database files that include any fields of data type BLOB (binary large object), CLOB (character large object), or DBCLOB (double-byte character large object). See the DB2 UDB for iSeries SQL Programming Concepts and DB2 UDB for iSeries SQL Reference books for more information on these data types.
• Operations related to byte stream file write operations, Journal Code B, Entry type WA. See the Integrated file system information for more information about these journal entries.
• Operations related to data queue send operations, Journal Code Q, Entry types QK and QS. See the Journal management topic for more information on these journal entries.
• Any operations on specific records or files (journal code R or F) of tables or database files resulting in minimized entry specific data when the journal has MINENTDTA specified for the corresponding object type. See the Journal management topic for restrictions and usage of journal entries with minimized entry specific data.

If the incomplete data indicator is returned as a 1, then that indicates that the journal-entry specific data includes a pointer to additional data. Additionally, a pointer handle will be returned with the journal entry. This handle is associated with any allocations required to support the pointer processing.

The pointer must be used by the same process that called this API; it cannot be stored and used by a different process. The pointer can be used for read access only. See the Journal management topic for descriptions of the entry types that may include pointer data. The pointer can be used in the following way:

• It can be used directly to copy the data addressed to some other storage space.
• If the journal entry is a record entry (journal code R), the journal-entry specific data could be used for an update or insert operation to the database file through SQL. See the DB2 UDB for iSeries SQL Reference book for more information.

The pointer handles will be implicitly deleted when the process that requested the journal entries is ended.

These pointers can be used only with the V4R4M0 or later versions of the following languages:

• ILE COBOL
• ILE RPG
• ILE C if the TERASPACE parameter is used when compiling the program. See the WebSphere Development Studio: ILE C/C++ Programmer's Guide book for more information.

Once the pointer data is used, you must delete the pointer handle to free the handle and any allocations associated with that handle. This can be done by using the Delete Pointer Handle (QjoDeletePointerHandle) API. If the handles are not deleted, the maximum number allowed can be reached, which will prevent further retrieval of journal entries. The deletion must occur from the same process that called the Retrieve Journal Entries (QjoRetrieveJournalEntries) API.

Even if the journal entry data is not used, all pointer handles returned to the user through this interface should be deleted. This is also true when partial journal entry information is returned, even though an error message was returned.

Note: No system function will prevent the deletion of journal receivers that may have outstanding pointer handles. If you want to prevent the journal receivers from being deleted prior to your use of the pointers, you may want to consider using the Delete Journal Receiver exit point, QIBM_QJO_DLT_JRNRCV.

Error Messages

Message ID	Error Message Text
CPF24B4 E	Severe error while addressing parameter list.
CPF3CF1 E	Error code parameter not valid.
CPF3C21 E	Format name &1 is not valid.
CPF3C4D E	Length &1 for key &2 not valid.
CPF3C82 E	Key &1 not valid for API &2.
CPF3C88 E	Number of variable length records &1 is not valid.
CPF3C90 E	Literal value cannot be changed.
CPF694A E	Number of fields &1 for key &2 is not valid.
CPF694B E	Length &1 of variable record for key &2 not valid.
CPF694C E	Variable length record data for key &1 not valid.
CPF6946 E	Number &1 specified for key &2 not valid.
CPF6948 E	Length of the receiver variable &1 is not valid.
CPF6949 E	Pointer to a receiver variable is not valid.
CPD7061 E	FROMENT and FROMTIME parameters cannot be used together.
CPD7062 E	TOENT and TOTIME parameters cannot be used together.
CPD7076 E	Value specified for JRNCDE not valid.
CPD7078 E	Duplicate journal code not valid.
CPF7002 E	File &1 in library &2 not a physical file.
CPF7006 E	Member &3 not found in file &1 in &2.
CPF7007 E	Cannot allocate member &3 file &1 in &2.
CPF701B E	Journal recovery of interrupted operation failed.
CPF705C E	INCENT(*ALL) not allowed for a local journal.
CPF7053 E	Values for RCVRNG parameter not correct; reason code &1.
CPF7054 E	FROM and TO values not valid.
CPF7055 E	Maximum number of files and members exceeded.
CPF7057 E	*LIBL not allowed with FILE(*ALL).
CPF706A E	Significant null value indicator truncated.
CPF7060 E	Object not found and not journaled in specified receiver range.
CPF7061 E	Conversion of journal entries failed.
CPF7062 E	No entries converted or received from journal &1.
CPF7065 E	Entry type (ENTTYP) not valid for journal code (JRNCDE).
CPF7074 E	RCVRNG for specified SEARCH not valid.
CPF708D E	Journal receiver found logically damaged.
CPF709C E	JOB, PGM, and USRPRF not valid for receiver range.
CPF70A9 E	OBJPATH parameter not valid for a remote journal.
CPF70AC E	FID &1 not found.
CPF8100 E	All CPF81xx messages could be returned. xx is from 01 to FF.
CPF9801 E	Object &2 in library &3 not found.
CPF9802 E	Not authorized to object &2 in &3.
CPF9803 E	Cannot allocate object &2 in library &3.
CPF9809 E	Library &1 cannot be accessed.
CPF9810 E	Library &1 not found.
CPF9820 E	Not authorized to use library &1.
CPF9822 E	Not authorized to file &1 in library &2.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

Example

See Code disclaimer information for information pertaining to code examples.

The following example retrieves one journal entry based on four keys that we will pass in the Variable Length Record structure.

/**********************************************************************/
/* Setup instructions:						      */
/*	CRTLIB     RJESAMPLE					      */
/*	CRTJRNRCV  JRNRCV(RJESAMPLE/R1)				      */
/*	CRTJRN     JRN(RJESAMPLE/J1) JRNRCV(RJESAMPLE/R1)	      */
/*	CRTPF	   FILE(RJESAMPLE/F1) RCDLEN(12)		      */
/*	STRJRNPF   FILE(RJESAMPLE/F1) JRN(RJESAMPLE/J1) IMAGES(*BOTH) */
/* Create some journal entries:					      */
/*	STRSQL							      */
/*	INSERT INTO RJESAMPLE/F1 VALUES ('REC1')		      */
/*	INSERT INTO RJESAMPLE/F1 VALUES ('REC2')		      */
/*	INSERT INTO RJESAMPLE/F1 VALUES ('REC3')		      */
/*	DELETE FROM RJESAMPLE/F1 WHERE F1 = 'REC2'		      */
/*	F3 to exit, then ENTER					      */
/*								      */
/* In this example, we are only going to retrieve one journal entry.  */
/* When you retrieve more than one, you can just increase the size    */
/* of the receiver variable and then work through the data using the  */
/* displacement values returned in the structure.  All of the         */
/* structures used here are based on structures defined or are        */
/* structures defined in QSYSINC/QJOURNAL.                            */
/**********************************************************************/

/* Some include files we will need */
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <ctype.h>
#include <qusec.h>
#include <qmhsndpm.h>
#include <qjournal.h>

/* Some constants we should define */
#define LIB  "RJESAMPLE "
#define JRN  "J1        "
#define RCV  "R1        "
#define FILE "F1        "
#define SEQ  "00000000000000000014"

/* These are declares for the Variable Length Record structure
   for the keys */
typedef _Packed struct 
{
   Qjo_JE_Fmt_Var_Len_Rcrd_t   base_structure;
   Qjo_JE_Data_t               Data[9004];
} Qjo_JE_Fmt_Var_Len_Rcrd_varlen_t;

typedef _Packed struct 
{
   Qjo_JE_Jrn_Info_Retrieve_t  base_structure;
   Qjo_JE_Fmt_Var_Len_Rcrd_varlen_t Fmt_Var_Len_Rcrd[4];
} Qjo_JE_Jrn_Info_Retrieve_varlen_t;


/* Function prototypes */
void buildKey1(Qjo_JE_Data_Key_1_t*);
void buildKey2(Qjo_JE_Data_Key_2_t*);
void buildKey4(Qjo_JE_Data_Key_4_t*);
void buildKey6(Qjo_JE_Data_Key_6_t*);
void copyKeysToVLR(Qjo_JE_Data_Key_1_t*, Qjo_JE_Data_Key_2_t*,
		   Qjo_JE_Data_Key_4_t*, Qjo_JE_Data_Key_6_t*,
		   Qjo_JE_Jrn_Info_Retrieve_varlen_t*);
void printEntryInfo(Qjo_RJNE0100_Hdr_t*);
void sendMsg(int, char*);


const short VLRSize = sizeof(Qjo_JE_Fmt_Var_Len_Rcrd_varlen_t);

void main()
{
    /* declare the key structures - we will input keys 1, 2, 4, and 6 */
    Qjo_JE_Data_Key_1_t   key1;
    Qjo_JE_Data_Key_2_t   key2;
    Qjo_JE_Data_Key_4_t   key4;
    Qjo_JE_Data_Key_6_t   key6;

    /* declare the structure that will hold the keys */
    Qjo_JE_Jrn_Info_Retrieve_varlen_t infoRetrieve;

    /* Misc variables */
    char qualJrnName[20];
    Qus_EC_t *errCode;
    char errorbuffer[17];
    long int lenRcvVar = 2048;

    /* declare the header structure for format RJNE0100 */
    Qjo_RJNE0100_Hdr_t         *rjne0100Hdr;

    /* build the key structures */
    buildKey1(&key1);
    buildKey2(&key2);
    buildKey4(&key4);
    buildKey6(&key6);

    /* Copy the key structures into Format variable length records */
    memset(&(infoRetrieve), 0x00,
	   sizeof(Qjo_JE_Jrn_Info_Retrieve_varlen_t));
    infoRetrieve.base_structure.Num_Var_Len_Rcrds = 0;
    copyKeysToVLR(&key1, &key2, &key4, &key6, &infoRetrieve);

    /* Set up the qualified journal name */
    memcpy(qualJrnName, JRN, sizeof(JRN));
    memcpy(qualJrnName+10, LIB, sizeof(LIB));

    /* Tell the error code structure we want data returned to the
       job log */
    errCode = (Qus_EC_t *) errorbuffer;
    errCode->Bytes_Provided = 0;

    /* Allocate the receiver space */
    if((rjne0100Hdr = (Qjo_RJNE0100_Hdr_t *) malloc(lenRcvVar)) != NULL)
    {
	rjne0100Hdr->Bytes_Returned = 0;

	/* Call the API */
	QjoRetrieveJournalEntries(rjne0100Hdr,
				  &lenRcvVar,
				  qualJrnName,
				  "RJNE0100",
				  &infoRetrieve,
				  errCode);

	/* Display the entry information returned (send to job log) */
	printEntryInfo(rjne0100Hdr);
	free(rjne0100Hdr);
    }
    /* That's it :) */
}

void buildKey1(Qjo_JE_Data_Key_1_t *key1)
{
    /* Initialize to all blanks */
    memset(key1, ' ', sizeof(Qjo_JE_Data_Key_1_t));

    /* We will use R1 as both the starting and ending receiver */

    /* Do the starting receiver and receiver lib first */
    memcpy(&(key1->Receiver_Range.Starting_Jrn_Rcv_Name),
	   RCV, sizeof(Qjo_Jrn_Rcv_Name_t));
    memcpy(&(key1->Receiver_Range.Starting_Jrn_Rcv_Lib_Name),
	   LIB, sizeof(Qjo_Jrn_Rcv_Lib_Name_t));

    /* Then do the ending receiver and receiver lib */
    memcpy(&(key1->Receiver_Range.Ending_Jrn_Rcv_Name),
	   RCV, sizeof(Qjo_Jrn_Rcv_Name_t));
    memcpy(&(key1->Receiver_Range.Ending_Jrn_Rcv_Lib_Name),
	   LIB, sizeof(Qjo_Jrn_Rcv_Lib_Name_t));
}

void buildKey2(Qjo_JE_Data_Key_2_t *key2)
{
    /* We will look for the sequence number of the delete entry (R DL).
       On a V5R2 system, that is journal sequence number 14 based on
       the instructions above.  Starting seq num is 14.                */

    /* Initialize key2 structure to NULL */
    memset(key2, 0x00, sizeof(Qjo_JE_Data_Key_2_t));
    memcpy(&(key2->Starting_Seq_Num), SEQ, sizeof(Qjo_Seq_Num_t));
}

void buildKey4(Qjo_JE_Data_Key_4_t *key4)
{
    /* We will look for the sequence number of the delete entry (R DL).
       On a V5R2 system, that is journal sequence number 14 based on
       the instructions above.  Ending seq num is 14.                  */

    /* Initialize key4 structure to NULL */
    memset(key4, 0x00, sizeof(Qjo_JE_Data_Key_4_t));
    memcpy(&(key4->Ending_Seq_Num), SEQ, sizeof(Qjo_Seq_Num_t));
}

void buildKey6(Qjo_JE_Data_Key_6_t *key6)
{
    /* Initialize key6 to NULL */
    memset(key6, 0x00, sizeof(Qjo_JE_Data_Key_6_t));

    /* We will only look for one entry - the R DL entry */
    key6->Number_Entries = 1;
}

void copyKeysToVLR(Qjo_JE_Data_Key_1_t *key1, Qjo_JE_Data_Key_2_t *key2,
		   Qjo_JE_Data_Key_4_t *key4, Qjo_JE_Data_Key_6_t *key6,
		   Qjo_JE_Jrn_Info_Retrieve_varlen_t *infoRetrieve)
{
    short i = infoRetrieve->base_structure.Num_Var_Len_Rcrds;

    /* Key 1 copy */
    infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Len_Var_Len_Rcrd
                  = VLRSize;
    infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Key = 1;
    infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Len_Of_Data =
      sizeof(Qjo_JE_Data_Key_1_t);
    memcpy(&(infoRetrieve->Fmt_Var_Len_Rcrd[i].Data),
          key1, sizeof(Qjo_JE_Data_Key_1_t));
   infoRetrieve->base_structure.Num_Var_Len_Rcrds++;
   i++;

   /* Key 2 copy */
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Len_Var_Len_Rcrd
                 = VLRSize;
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Key = 2;
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Len_Of_Data = 
      sizeof(Qjo_JE_Data_Key_2_t);
   memcpy(&(infoRetrieve->Fmt_Var_Len_Rcrd[i].Data),
          key2, sizeof(Qjo_JE_Data_Key_2_t));
   infoRetrieve->base_structure.Num_Var_Len_Rcrds++;
   i++;

   /* Key 4 copy */
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Len_Var_Len_Rcrd
                 = VLRSize;
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Key = 4;
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Len_Of_Data = 
      sizeof(Qjo_JE_Data_Key_4_t);
   memcpy(&(infoRetrieve->Fmt_Var_Len_Rcrd[i].Data),
          key4, sizeof(Qjo_JE_Data_Key_4_t));
   infoRetrieve->base_structure.Num_Var_Len_Rcrds++;
   i++;

   /* Key 6 copy */
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Len_Var_Len_Rcrd
                 = VLRSize;
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Key = 6;
   infoRetrieve->Fmt_Var_Len_Rcrd[i].base_structure.Len_Of_Data =
      sizeof(Qjo_JE_Data_Key_6_t);
   memcpy(&(infoRetrieve->Fmt_Var_Len_Rcrd[i].Data),
          key6, sizeof(Qjo_JE_Data_Key_6_t));
   infoRetrieve->base_structure.Num_Var_Len_Rcrds++;
}

void printEntryInfo(Qjo_RJNE0100_Hdr_t *rjne0100Hdr)
{
    char msg[50];
    Qjo_RJNE0100_JE_Hdr_t *entry_ptr;

    /* get a pointer to the entry */
    entry_ptr = (Qjo_RJNE0100_JE_Hdr_t *)((char *)rjne0100Hdr +
       rjne0100Hdr->Offset_First_Jrn_Entry);

    /* Access the data of interest - we will just print the header,
       sequence number, journal code, and entry type to ensure
       we got the R DL entry */
    memset(msg, ' ', sizeof(msg));
    sprintf(msg, "JH:Bytes Rtrnd:%d\n", rjne0100Hdr->Bytes_Returned);
    sendMsg(sizeof(msg), msg);

    memset(msg, ' ',sizeof(msg));
    sprintf(msg, "JH:Dsp to 1st JEH:%d\n",
	    rjne0100Hdr->Offset_First_Jrn_Entry);
    sendMsg(sizeof(msg), msg);

    memset(msg, ' ',sizeof(msg));
    sprintf(msg, "JH:Num ent rtrv:%d\n",
             rjne0100Hdr->Number_Entries_Retreived);
    sendMsg(sizeof(msg), msg);

    memset(msg, ' ',sizeof(msg));
    sprintf(msg, "JH:Cont Hndl:%1.1s\n",
             (char *)&rjne0100Hdr->Continuation_Handle);
    sendMsg(sizeof(msg), msg);

    memset(msg, ' ',sizeof(msg));
    sprintf(msg, "Seq #:%-20.20s\n", entry_ptr->Seq_Number);
    sendMsg(sizeof(msg), msg);

    memset(msg, ' ',sizeof(msg));
    sprintf(msg, "Jrn code:%1.1s\n", (char *)&entry_ptr->Jrn_Code);
    sendMsg(sizeof(msg), msg);

    memset(msg, ' ',sizeof(msg));
    sprintf(msg, "Entry type:%-2.2s\n", entry_ptr->Entry_Type);
    sendMsg(sizeof(msg), msg);
}

void sendMsg(int length, char *message)
{
    char   msgid[8]       = "CPF9897";                         
    char   path[21]       = "QCPFMSG   *LIBL     ";           
    char   msgtype[11]    = "*INFO     ";
    char   callstcken[11] = "*         ";
    int    callstckco     = 1;                               
    char   msgkey[5]      = "    ";                          
    Qus_EC_t *errCode;
    char   errorbuffer[512];

    errCode = (Qus_EC_t *) errorbuffer;
    errCode->Bytes_Provided = 0;

    QMHSNDPM(msgid, path, message, length, 
           msgtype, callstcken, callstckco, msgkey, 
           errCode);
}