Retrieve Journal Receiver Information (QjoRtvJrnReceiverInformation) API


  Required Parameter Group:


  Omissible Parameter:


  Service Program Name: QJOURNAL

  Header File: QSYSINC/H.QJOURNAL

  Default Public Authority: *USE

  Threadsafe: Yes

The Retrieve Journal Receiver Information (QjoRtvJrnReceiverInformation) API provides access to journal-receiver-related information to help manage a journal environment, including a remote journal environment.

Various types of journal receiver information are provided by the API, similar to information reported using the Display Journal Receiver Attributes (DSPJRNRCVA) CL command.


Authorities and Locks

Journal Receiver Authority
*OBJOPR and some data authority other than *EXECUTE
Journal Receiver Library Authority
*EXECUTE
Journal Authority
*OBJOPR
Journal Library Authority
*EXECUTE
Service Program Authority
*EXECUTE
Journal Receiver Lock
*SHRRD
Journal Lock
*SHRRD

For the following authorities and locks:

These are required only if the journal receiver has ever been associated with a journal, and that journal is on the system.


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 provided. The length of receiver variable parameter may be specified up to the size of the 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. The minimum length is 8 bytes.

Qualified journal receiver name
INPUT; CHAR(20)

The name of the journal receiver and its library from which the journal receiver attributes and information is to be retrieved. The first 10 characters contain the journal receiver name, and the second 10 characters contain the library name. The special values supported for the library name follow:

Format name
INPUT; CHAR(8)

The format RRCV0100 is the only supported format that is used by this API. For more information, see RRCV0100 Format.


Omissible Parameter

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.


RRCV0100 Format

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


Field Descriptions

Attached date and time. The date and time that this journal receiver was attached to the journal. For a journal receiver attached to a *REMOTE journal, this is the date and time that the journal receiver was attached on the local system. This field is in the CYYMMDDHHMMSS format as follows:

Auxiliary storage pool (ASP). The number of the auxiliary storage pool to which storage for the object is allocated.

ASP device name. The name of the independent auxiliary storage pool (ASP) device to which storage for the object is allocated. *SYSBAS is used to indicate the system ASP and all basic user ASPs.

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.

Detached date and time. The date and time that this journal receiver was detached from the journal. For a journal receiver attached to a *REMOTE journal, this is the date and time that the journal receiver was detached on the local system. This field is in the CYYMMDDHHMMSS format, which is described in the attached date and time field description.

Dual journal receiver library name. The name of the library that contains the dual journal receiver.

This field is blank if there is no dual receiver.

Dual journal receiver name. The journal receiver that was attached at the same time as the journal receiver.

This field is blank if there is no dual receiver.

Filter by object. Specifies whether or not journal entries sent to this remote journal receiver from a local journal were filtered by object.

The possible values follow:


Filter by program. Specifies qualified program names. The number of qualified program names in the array is controlled by the Number of programs to filter field. Journal entries sent on behalf of these programs were filtered for this remote journal receiver.

The first 10 characters contain the program name, and the second 10 characters contain the name of the program's library.

Note: The offset to the filter by program array for each environment is determined by the Offset to filter by program array field.

The possible values for program library name are:


Filter images. Specifies whether or not before images sent to this remote journal receiver were filtered.

The possible values follow:


First sequence number. The journal sequence number of the first journal entry in this journal receiver.

This field will be -1 if the value could not fit in the specified Binary(4) field. The complete value will be in the First sequence number - long field.

First sequence number - long. This is the same field as First sequence number except the information is in a Char(20) field which is treated as Zoned(20,0).

Fixed length data *JOB. Indicates whether the job name will be stored when journal entries are deposited.

Fixed length data *LUW. Indicates whether the logical unit of work identifier will be stored when journal entries are deposited.

Fixed length data *PGM. Indicates whether the program name will be stored when journal entries are deposited.

Fixed length data *PGMLIB. Indicates whether the program library name will be stored when journal entries are deposited.

Fixed length data *RMTADR. Indicates whether the remote address will be stored when journal entries are deposited.

Fixed length data *SYSSEQ. Indicates whether the system sequence number will be stored when journal entries are deposited.

Fixed length data *THD. Indicates whether the thread identifier will be stored when journal entries are deposited.

Fixed length data *USR. Indicates whether the user name will be stored when journal entries are deposited.

Fixed length data *XID. Indicates whether the transaction identifier will be stored when journal entries are deposited.



Journal entries filtered. Indicates whether or not some journal entries present on a local journal receiver may have been filtered out and are not present in this journal receiver.

Journal library name. The name of the library in which the journal is stored.

This field is blank if this journal receiver is not yet associated with any journal.

Journal name. The name of the journal.

This field is *NONE if this journal receiver is not yet associated with any journal.

Journal receiver library name. The name of the library that contains the journal receiver.

Journal receiver name. The name of the journal receiver.

Last sequence number. The journal sequence number of the last journal entry in this journal receiver.

This field will be -1 if the value could not fit in the specified Binary(4) field. The complete value will be in the Last sequence number - long field.

Last sequence number - long. This is the same field as Last sequence number except the information is in a Char(20) field which is treated as Zoned(20,0).

Local journal ASP group name. The name of the independent auxiliary storage pool (ASP) group of the local journal. *SYSBAS is used to indicate the system ASP and all basic user ASPs. The local journal is the journal that is the initiator of the original journal deposit that has been replicated downstream to this journal.

This field is blank if there is no local journal.

Local journal library name. The library name of the local journal. The local journal is the journal that is the initiator of the original journal deposit that has been replicated downstream to this journal.

This field is blank if there is no local journal.

Local journal name. The journal name of the local journal. The local journal is the journal that is the initiator of the original journal deposit that has been replicated downstream to this journal.

This field is blank if there is no local journal.

This field is *NONE if this journal receiver is not yet associated with any journal.

Local journal receiver library name. The library name of the local journal receiver that is associated with the local journal. The local journal is the journal that is the initiator of the original journal deposit that has been replicated downstream to this journal.

This field is blank if there is no local journal.

This field is *NONE if this journal receiver is not yet associated with any journal.

Local journal system. The system name of the local journal. The local journal is the journal that is the initiator of the original journal deposit that has been replicated downstream to this journal.

This field is blank if there is no local journal.

Maximum entry-specific data length. The length in bytes of the longest entry-specific data among all journal entries in this journal receiver.

This field will be -1 if the value could not fit in the specified Binary(4) field. The complete value will be in the Maximum entry-specific data length - long field.

Maximum entry-specific data length - long. This is the same field as Maximum entry-specific data length except the information is in a Char(20) field which is treated as Zoned(20,0).

Maximum null value indicators. The maximum number of null value indicators among all journal entries in this journal receiver.

Minimize entry specific data for data areas. Whether the receiver was attached when MINENTDTA(*DTAARA) was in effect for the journal. Possible values follow:

If this journal receiver is associated with a remote journal, then the value for this field was determined by the local journal.

Minimize entry specific data for files. Whether the receiver was attached when MINENTDTA(*FILE) was in effect for the journal. Possible values follow:

If this journal receiver is associated with a remote journal, then the value for this field was determined by the local journal.

Next dual journal receiver library name. The library name of the next dual journal receiver that is associated with this journal receiver.

This field is blank if there is no next dual journal receiver, or if the specified journal receiver is currently associated with a remote journal.

Next dual journal receiver name. The name of the next dual journal receiver that is associated with this journal receiver.

This field is blank if there is no next dual journal receiver, or if the specified journal receiver is currently associated with a remote journal.

Next journal receiver library name. The library name of the next journal receiver that is associated with this journal receiver.

This field is blank if there is no next journal receiver, or if the specified journal receiver is currently associated with a remote journal.

Next journal receiver name. The name of the next journal receiver that is associated with this journal receiver.

This field is blank if there is no next journal receiver, or if the specified journal receiver is currently associated with a remote journal.

Number of journal entries. The number of journal entries that are contained in this journal receiver.

This field will be -1 if the value could not fit in the specified Binary(4) field. The complete value will be in the Number of journal entries - long field.

Number of journal entries - long. This is the same field as Number of journal entries except the information is in a Char(20) field which is treated as Zoned(20,0).

Number of programs to filter. The number of programs specified in the filter by program array.

If the receiver is not a remote receiver, this field will be -1.

Offset to filter by program array. The byte offset from the beginning of the receiver variable to the first program that had its journal entries filtered from this remote receiver.

Pending transactions. Whether the journal receiver contains journal entries for commitment control transactions that have not yet been committed or rolled back. The possible values are:

Previous dual journal receiver library name. The library name of the previous dual journal receiver that is associated with this journal receiver.

This field is blank if there is no previous dual journal receiver, or if the specified journal receiver is currently associated with a remote journal.

Previous dual journal receiver name. The name of the previous dual journal receiver that is associated with this journal receiver.

This field is blank if there is no previous dual journal receiver, or if the specified journal receiver is currently associated with a remote journal.

Previous journal receiver library name. The library name of the previous journal receiver that is associated with this journal receiver.

This field is blank if there is no previous journal receiver, or if the specified journal receiver is currently associated with a remote journal.

Previous journal receiver name. The name of the previous journal receiver that is associated with this journal receiver.

This field is blank if there is no previous journal receiver, or if the specified journal receiver is currently associated with a remote journal.

Receiver maximums option. Indicates the journal receiver sequence number and size option for this journal receiver. Possible values follow:

If this journal receiver is associated with a remote journal, then the value for this field was determined by the local journal.

Receiver size option *MINFIXLEN. The size of the journal entries that are deposited into the attached journal receivers is reduced by the automatic removal of all fixed length data such as job name, system sequence number, and so on. This option is applicable only for local journals and is blank for remote journals.



Redirected journal receiver library. If this journal receiver was attached to a remote journal, this field is the *TYPE1 receiver library redirection that was in effect when this journal receiver was attached.

This field is blank if this journal receiver was attached to a local journal, or if the journal receiver was attached to a remote journal with no *TYPE1 receiver library redirection.

This field is *NONE if this journal receiver is not yet associated with any journal.

Remote journal type. If this journal receiver was attached to a remote journal, this field is the remote journal type for that journal, when this journal receiver was attached. The possible values are:

Reserved. The bytes reserved to align binary fields or for future use.

Saved date and time. The date and time that the journal receiver was last saved. This value reflects when the receiver was saved from the system it exists on (either the source or target system time). This field is in the CYYMMDDHHMMSS format, which is described in the attached date and time field description.

Size. The number of kilobytes of auxiliary disk storage used by this journal receiver.

Source journal ASP group name. The name of the independent auxiliary storage pool (ASP) group of the source journal. *SYSBAS is used to indicate the system ASP and all basic user ASPs. The source journal is the journal that is directly upstream of this journal.

This field is blank if there is no source journal.

Source journal library name. The library name of the source journal. The source journal is the journal that is directly upstream of this remote journal.

This field is blank if there is no source journal.

Source journal name. The journal name of the source journal. The source journal is the journal that is directly upstream of this remote journal.

This field is blank if there is no source journal.

This field is *NONE if this journal receiver is not yet associated with any journal.

Source journal receiver library name. The library name of the source journal receiver that is associated with the source journal. The source journal is the journal that is directly upstream of this remote journal.

This field is blank if there is no source journal.

This field is *NONE if this journal receiver is not yet associated with any journal.

Source journal system. The system name of the source journal. The source journal is the journal that is directly upstream of this remote journal.

This system name is determined when the remote journal is activated by using the Change Remote Journal (CHGRMTJRN) command or by calling the Change Journal State (QjoChangeJournalState) API, and is based on the current system name at that time as seen by using the Display Network Attributes (DSPNETA) command.

This field is blank if there is no source journal.

Status. The status of the journal receiver. The status can be one of the following:

Text. The text description of the journal receiver.

Threshold. An auxiliary disk storage space threshold value (in kilobytes) for the journal receiver. If the threshold value is exceeded during journaling and the journal has the MNGRCV(*USER) attribute, a message (CPF7099) is sent to the message queue that is specified on the Create Journal (CRTJRN) or the Change Journal (CHGJRN) command. If the journal has the MNGRCV(*SYSTEM) attribute, the system creates and attaches a new journal receiver, detaches the old journal receiver when the threshold is reached, and sends message CPF7020 to the journal message queue. This option is applicable only for local journals and is zero for remote journals.

Error Messages



API introduced: V4R2

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