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 operation1 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 | ||
| 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 ]