Retrieve Journal Identifier Information (QJORJIDI) API

Required Parameter Group:

1	Receiver variable	Output	Char(*)
2	Length of receiver variable	Input	Binary(4)
3	Qualified journal name	Input	Char(20)
4	Journal identifier value	Input	Char(10)
5	Format name	Input	Char(8)
6	Error Code	I/O	Char(*)

Default Public Authority: *USE

Threadsafe: Yes

The Retrieve Journal Identifier Information (QJORJIDI) API retrieves the current name and type of the object associated with the specified journal identifier (JID) for the specified journal. A JID is unique; it is assigned to a particular object when journaling is started for the object. The JID associates the journal entries with a particular object. See Maintaining a JID for a Journaled Object for more information about how the system maintains a JID value for a journaled object.

This API retrieves the object name and type associated with a particular JID if:

The specified JID is associated with an object that is journaled to the specified journal.
The specified JID is associated with an object that was journaled to the specified journal, but the object has since been deleted and a change journal operation¹ has not yet attached a new receiver.
The specified JID is associated with an object that was journaled to the specified journal, but journaling has since been ended for the object and a change journal operation has not yet attached a new receiver. This is true even if the object is currently journaled to a different journal than the one specified.

This API cannot retrieve an object name for a specified JID if:

The specified JID was never associated with an object journaled to the specified journal.
The specified JID is associated with an object that was journaled to the specified journal, but the object has since been deleted and a change journal operation has attached a new receiver.
The specified JID is associated with an object that was journaled to the specified journal, but journaling has since been ended for the object and a change journal operation has attached a new receiver.

Note: The change journal operation can be a user initiated Change Journal (CHGJRN) command or from system change-journal management support. System change-journal management support is activated by a Create Journal (CRTJRN) or Change Journal (CHGJRN) command with the MNGRCV(*SYSTEM) parameter and value.

If an object name or file identifier cannot be retrieved, blanks are returned for the object name, library name, member name, type, and object file identifier.

The JID for the object associated with a particular journal entry is in the fixed-length portion of the journal entry when specifying:

OUTPUT(*OUTFILE) and OUTFILFMT(*TYPE4 or *TYPE5) on the Display Journal (DSPJRN) command.
ENTFMT(*TYPE4 or *TYPEPTR) or ENTFMT(*JRNENTFMT) and JRNENTFMT(RJNE0200) on the Receive Journal Entry (RCVJRNE) command.
ENTFMT(*TYPE4 or *TYPE5) on the Retrieve Journal Entry (RTVJRNE) command.

Maintaining a JID for a Journaled Object

The following are the system rules for maintaining a JID for a journaled object:

A JID is assigned for a journaled object when journaling is first started for the object. For example, when journaling is started for a database file with a single member, a JID value is assigned to the data portion of the member. If two members exist in the file, a different JID is assigned to the data portion for each member.
The JID remains the same for the journaled object if:
- The object is moved to a different library.
- The object is renamed.
- Journaling is ended for the object, and then started again to either the same journal or to a different journal.
- The object is saved while being journaled, deleted from the system, and then restored from the saved version. This is true whether the object is being restored to the original system from which it was saved or to a different system, as long as the same version of the object does not already exist on that system.
The JID does not remain the same for the journaled object if:
- The object is deleted, and then created again. When journaling is started for the newly created object, a new JID is assigned. The object retains its original JID when the Replay Database Operation (QDBRPLAY) API or the Replay Journal Entry (QjoReplayJournalEntry) API is used to recreate the object.
- The object is saved while being journaled, then renamed or moved to another library, and then the object is restored using the saved version. The restored version will be assigned a new JID because the original JID for the object is currently assigned to the original object that was renamed or moved to a different library.

See the Journal management topic for more information about what object types are associated with the various types of journal entries.

Restrictions

The specified journal cannot be a remote journal.

Authorities and Locks

Journal Authority: *USE, *OBJEXIST
Journal Library Authority: *EXECUTE
Currently Attached Receiver Authority: *USE
Currently Attached Receiver Library Authority: *EXECUTE
Journal Lock: *SHRRD

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that is to receive the information 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.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable. The length must be at least 8 bytes. If the variable is not long enough to hold the information, the data is truncated. If the length is larger than the size of the receiver variable, the results beyond the length of the largest format are not predictable.

Qualified journal name

INPUT; CHAR(20)

The name of the journal that is to be used when retrieving the JID information and the library in which it resides. The first 10 characters contain the journal name and the second 10 characters contain the library name. The special values supported for the library name are:

*LIBL	Library list
*CURLIB	Current library

Journal identifier (JID) value

INPUT; CHAR(10)

The journal identifier (JID) value that is to be used for the retrieve operation. Information will be retrieved based on this JID value.

Format name

INPUT; CHAR(8)

The format name RJID0100 is the only valid format name used bythis API. For more information, see RJID0100 Format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

RJID0100 Format

The structure of the information returned is determined by the specified format name. For detailed descriptions of the fields, see Field Descriptions.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	CHAR(10)	Journal name
18	12	CHAR(10)	Journal library name
28	1C	CHAR(10)	Journal identifier (JID) value
38	26	CHAR(10)	Object name
48	30	CHAR(10)	Object library name
58	3A	CHAR(10)	Member name
68	44	CHAR(10)	Object type
78	4E	CHAR(16)	Object file identifier

Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Journal identifier (JID) value. The JID value used to retrieve the object name, object library name, member name, and object type.

Journal library name. The name of the library for the journal. If *LIBL or *CURLIB was specified as input, then this field will contain the actual library name for the journal.

Journal name. The name of the journal.

Member name. If the object type is *QDDS or *QDDSI, then this field contains the member name. Otherwise, this field is returned as blanks.

Object file identifier. The file identifier of the object associated with the specified JID value. If the object name could not be retrieved for the specified JID value, then this field is returned as blanks. File identifiers are unique identifiers associated with integrated file system related objects. The Get Path Name of Object from Its File ID (Qp0lGetPathFromFileID) API can be used to find the path name of an object using the file identifier.

If the object type is not *DIR, *STMF, or *SYMLNK, then this field is returned as blanks.

Object library name. The name of the library for the object associated with the specified JID value. If the object name could not be retrieved for the specified JID value, then this field is returned as blanks.

If the object type is *DIR, *STMF, or *SYMLNK, then this field is returned as blanks.

Object name. The name of the object associated with the specified JID value. If the object name could not be retrieved for the specified JID value, then this field is returned as blanks.

If the object type is *DIR, *STMF, or *SYMLNK, then this field is returned as blanks.

Object type. The type of the object associated with the specified JID value. If the object name could not be retrieved for the specified JID value, then this field is returned as blanks. The following lists the valid object types that can be retrieved for a specified JID value:

*DIR	Integrated file system directory
*DTAARA	Data area
*DTAQ	Data queue
*FILE	Data base file
*JRNRCV	Journal receiver
*LIB	Library
*QDDS	Data portion of a database member
*QDDSI	Access path for a database member
*STMF	Integrated file system stream file
*SYMLNK	Integrated file system symbolic link

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.
CPF3C24 E	Length of the receiver variable is not valid.
CPF3C90 E	Literal value cannot be changed.
CPF6958 E	No attached receiver can be used.
CPF701B E	Journal recovery of interrupted operation failed.
CPF705A E	Operation failed due to remote journal.
CPF708D E	Journal receiver found logically damaged.
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.
CPF9810 E	Library &1 not found.
CPF9820 E	Not authorized to use library &1.
CPF9825 E	Not authorized to device &1.
CPF9830 E	Cannot assign library &1.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

API introduced: V3R1

[ Back to top | Journal and Commit APIs | APIs by category ]