Create Journal (CRTJRN)

The Create Journal (CRTJRN) command creates a journal as a local journal with the specified attributes, and attaches the specified journal receiver to the journal. Once a journal is created, object changes can be journaled to it or user entries can be sent to it. The journal state of the created journal is *ACTIVE.

Restrictions:

Parameters

Keyword Description Choices Notes
JRN Journal Qualified object name Required, Positional 1
Qualifier 1: Journal Name
Qualifier 2: Library Name, *CURLIB
JRNRCV Journal receiver Values (up to 2 repetitions): Qualified object name Required, Positional 2
Qualifier 1: Journal receiver Name
Qualifier 2: Library Name, *LIBL, *CURLIB
ASP ASP number 1-32, *LIBASP Optional
MSGQ Journal message queue Qualified object name Optional
Qualifier 1: Journal message queue Name, QSYSOPR
Qualifier 2: Library Name, *LIBL, *CURLIB
MNGRCV Manage receivers *SYSTEM, *USER Optional
DLTRCV Delete receivers *NO, *YES Optional
RCVSIZOPT Receiver size options Single values: *SYSDFT, *NONE
Other values (up to 3 repetitions): *RMVINTENT, *MINFIXLEN, *MAXOPT1, *MAXOPT2, *MAXOPT3
Optional
MINENTDTA Minimize entry specific data Single values: *NONE
Other values (up to 2 repetitions): *FILE, *FLDBDY, *DTAARA
Optional
JRNCACHE Journal caching *NO, *YES Optional
MNGRCVDLY Manage receiver delay time 1-1440, 10 Optional
DLTRCVDLY Delete receiver delay time 1-1440, 10 Optional
FIXLENDTA Fixed length data Single values: *JOBUSRPGM
Other values (up to 9 repetitions): *JOB, *USR, *PGM, *PGMLIB, *SYSSEQ, *RMTADR, *THD, *LUW, *XID
Optional
JRNOBJLMT Journal object limit *MAX250K, *MAX10M Optional
TEXT Text 'description' Character value, *BLANK Optional
AUT Authority Name, *LIBCRTAUT, *CHANGE, *ALL, *USE, *EXCLUDE Optional

Journal (JRN)

Specifies the qualified name of the journal to be created.

This is a required parameter.

Qualifier 1: Journal

journal-name
Specify the name of the journal that is being created.

Qualifier 2: Library

*CURLIB
The journal is created in the current library for the job. If no library is specified as the current library for the job, QGPL is used.
library-name
Specify the library where the journal is to be created.

Journal receiver (JRNRCV)

Specifies the journal receiver to be attached to the specified journal.

Up to 2 journal receivers can be specified, but the second journal receiver is ignored.

This is a required parameter.

Qualifier 1: Journal receiver

receiver-name
Specify the name of the journal receiver.

The journal receiver must not have been previously attached to a journal or have been in the process of being attached to a journal.

Qualifier 2: Library

*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.
library-name
Specify the name of the library to be searched.

ASP number (ASP)

Specifies the auxiliary storage pool (ASP) from which the system allocates storage for the journal.

*LIBASP
The storage space for the journal is allocated from the same auxiliary storage pool as the storage space of the journal's library. Use this value if you want the journal in an independent user ASP.
ASP-identifier
Specify a value ranging from 1 through 32 to specify the identifier of the ASP from which to have the storage space of the journal allocated. Valid values depend on how ASPs are defined on the system. Specify an ASP number only if you want to place the journal in a basic non-library user ASP.

Note: The value of 1 is the system ASP, any other value indicates a user ASP.

Journal message queue (MSGQ)

Specifies the qualified name of the message queue associated with this journal. A message is sent to this queue when one of the following occurs:

To set the threshold value, refer to the Create Journal Receiver (CRTJRNRCV) or the Change Journal (CHGJRN) command descriptions.

Note: A message queue that is in the library QTEMP cannot be specified on this parameter.

Note: Some messages that are sent to the journal message queue will also be sent to the QSYSOPR message queue and QHST.

QSYSOPR
The message is sent to the QSYSOPR message queue.
journal-message-queue
Specify the name of the message queue to which the journal messages are sent. If this message queue is not available when a message is to be sent, the message is sent to the QSYSOPR message queue.
*LIBL
All libraries in the library list for the current thread are searched until the first match is found.
*CURLIB
The current library for the job is used to locate the journal message queue. If no library is specified as the current library for the job, QGPL is used.
library-name
Specify the library where the journal message queue is located.

Manage receivers (MNGRCV)

Specifies how the changing of journal receivers (detaching the currently attached journal receiver and attaching a new journal receiver) is managed.

*SYSTEM
The system manages the changing of journal receivers (this function is called system change-journal management). When an attached journal receiver reaches its size threshold, the system detaches the attached journal receiver and creates and attaches a new journal receiver. Message CPF7020 is sent to the journal message queue when the journal receiver is detached.

Also, if the journal receiver was attached while RCVSIZOPT(*MAXOPT1 or *MAXOPT2) was in effect for the journal, the system attempts to perform a CHGJRN command to reset the sequence number when the journal receiver's sequence number exceeds 9,900,000,000. If the journal receiver was attached while RCVSIZOPT(*MAXOPT3) was in effect for the journal, the system attempts to perform a CHGJRN command to reset the sequence number when the journal receiver's sequence number exceeds 18,446,644,000,000,000,000. For all other journal receivers, the system attempts this CHGJRN when the sequence number exceeds 2,147,000,000.

Additionally, during an initial program load (IPL) or the vary on of an independent ASP, the system performs a CHGJRN command to create and attach a new journal receiver and to reset the journal sequence number of journals that are not needed for commitment control recovery for that IPL or vary on, unless the RCVSIZOPT is *MAXOPT3. The sequence number will not be reset and a new journal receiver will not be attached if the RCVSIZOPT is *MAXOPT3 unless the sequence number exceeds the sequence number threshold which is 18,446,600,000,000,000,000. If there are outstanding commitment control transactions associated with one of these journals, a new journal receiver will be attached but the sequence number will not be reset. If there are less than three journal entries in the attached receiver for one of these journals at the time of the IPL, the system will not attempt to attach a new journal receiver.

Notes:

  1. The journal receiver threshold value must be specified with a value other than *NONE before this value is specified.
  2. Specifying MNGRCV(*SYSTEM) does not prevent you from using the CHGJRN command to manage journal receivers.
*USER
The user manages the changing of journal receivers by issuing the Change Journal (CHGJRN) command to attach a new receiver and detach the old receiver.

Delete receivers (DLTRCV)

Specifies whether the system deletes journal receivers when they are no longer needed or leaves them on the system for the user to delete after they have been detached by system change-journal management or by a user-issued CHGJRN command.

Note: This parameter can be specified only if MNGRCV(*SYSTEM) is specified.

*NO
The journal receivers are not deleted by the system.
*YES
The journal receivers are deleted by the system.

When the journal has the DLTRCV(*YES) attribute, the following conditions can prevent the system from deleting the receiver. When one of these conditions occurs, the system sends message CPI70E6 and then retries the delete operation every 10 minutes (or as often as requested via the DLTRCVDLY parameter) until the operation is successful.

  • A lock conflict occurs for either the journal receiver or its journal.
  • An exit program that was registered by way of the QIBM_QJO_DLT_JRNRCV exit point indicates that a receiver is not eligible for deletion.
  • A journal has remote journals associated with it and one or more of the associated remote journals do not yet have full copies of this receiver.

Receiver size options (RCVSIZOPT)

Specifies the options that affect the size of the receiver attached to the journal.

Single values

*SYSDFT
The system uses the current recommended values. Specifying this value is currently equivalent to specifying *MAXOPT2 and *RMVINTENT.
*NONE
No options affect the size of the journal entries attached to the receiver. All journal entries placed on the receiver are permanent. The fixed length data as defined by FIXLENDTA will be included in every journal entry deposited into the attached journal receiver. If this is specified for the journal, the journal receiver attached to that journal can have a maximum receiver size of approximately 2 gigabytes (2,147,483,647) and a maximum sequence number of 2,147,483,136. Additionally, the maximum size of the journal entry which can be deposited is 15,761,440 bytes.

Other values (up to 3 repititions)

*RMVINTENT
The size of the receiver attached to the journal is reduced by automatic removal of the internal entries required only for initial program load (IPL) or independent ASP vary on recovery when these entries are no longer required.
*MINFIXLEN
The size of the journal entries that are deposited into the attached journal receiver is reduced by the automatic removal of fixed-length data that is deemed not to be required for recovery purposes. This option is not valid when FIXLENDTA is also specified.
*MAXOPT1
If this is specified for the journal, the journal receiver attached to that journal can have a maximum receiver size of approximately one terabyte (1,099,511,627,776 bytes) and a maximum sequence number of 9,999,999,999. Additionally, the maximum size of the journal entry which can be deposited is 15,761,440 bytes. This value cannot be specified if *MAXOPT2 or *MAXOPT3 is specified.
*MAXOPT2
If this is specified for the journal, the journal receiver attached to that journal can have a maximum receiver size of approximately one terabyte (1,099,511,627,776 bytes) and a maximum sequence number of 9,999,999,999. Additionally, the maximum size of the journal entry which can be deposited is 4,000,000,000 bytes. This value cannot be specified if *MAXOPT1 or *MAXOPT3 is specified.
*MAXOPT3
If this is specified for the journal, the journal receiver attached to that journal can have a maximum receiver size of approximately one terabyte (1,099,511,627,776 bytes) and a maximum sequence number of 18,446,744,073,709,551,600. Additionally, the maximum size of the journal entry which can be deposited is 4,000,000,000 bytes. These journal receivers cannot be saved and restored to any releases prior to V5R3M0 nor can they be replicated to any remote journals on any systems at releases prior to V5R3M0. Also, during an initial program load (IPL) or the vary on of an independent ASP, when MNGRCV(*SYSTEM) is specified, the system will not automatically perform a CHGJRN command to create and attach a new journal receiver and reset the journal sequence number unless the sequence number exceeds the sequence number threshold which is 18,446,600,000,000,000,000. This value cannot be specified if *MAXOPT1 or *MAXOPT2 is specified.

Minimize entry specific data (MINENTDTA)

Specifies which object types allow journal entries to have minimized entry specific data.

Journal receivers using the *FLDBDY option to minimize the entry specific data cannot be saved and restored to any release prior to V5R4M0 nor can they be replicated to any remote journal on a system at a release prior to V5R4M0. See the Journal management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/ for restrictions and usage of journal entries with minimized entry specific data.

*NONE
No object type allows a journal entry with minimized entry specific data. Journal entries for all journaled objects will be deposited in the journal with complete entry specific data.
*FILE
Journaled files may have journal entries deposited with minimized entry specific data. The minimizing will not occur on field boundaries. Therefore, the entry specific data may not be viewable and may not be used for auditing purposes. This value cannot be specified if *FLDBDY is specified.
*FLDBDY
Journaled files may have journal entries deposited with minimized entry specific data. The minimizing for journaled files will occur on field boundaries. Therefore, the entry specific data will be viewable and may be used for auditing purposes
*DTAARA
Journaled data areas may have journal entries deposited with minimized entry specific data.

Journal caching (JRNCACHE)

Specifies whether journal entries will be cached before being written out to disk.

*NO
Journal entries are written to disk immediately if needed to assure single-system recovery.
*YES
Journal entries are written to main memory. When there are several journal entries in main memory, then the journal entries are written from main memory to disk. If the application performs large numbers of changes, this may result in fewer synchronous disk writes resulting in improved performance. However, it is not recommended to use this option if it is unacceptable to lose even one recent change in the event of a system failure where the contents of main memory are not preserved. This type of journaling is directed primarily toward batch jobs and may not be suitable for interactive applications where single system recovery is the primary reason for journaling.

Note: Applications using commitment control will likely see less performance improvement because commitment control already performs some journal caching.

Note: Entries that are in the cache are not displayable using the Display Journal (DSPJRN) command, Receive Journal Entries (RCVJRNE) command, Retrieve Journal Entries (RTVJRNE) command, or the QjoRetrieveJournalEntries API. Also, entries that are in the cache are not sent to a target system with remote journal. However, these journal entries are included in the last journal sequence number for the journal receiver returned via the Display Journal Receiver Attributes (DSPJRNRCVA) command or QjoRtvJrneReceiverInformation API.

Note: This value cannot be specified if the journal-name starts with a Q and the journal-library starts with a Q, unless the library is QGPL.

Manage receiver delay time (MNGRCVDLY)

Specifies the time (in minutes) to be used to delay the next attempt to attach a new journal receiver to this journal if the journal is system managed (MNGRCV(*SYSTEM)).

10
When the system cannot allocate an object needed to attach a new journal receiver to this journal, it will wait 10 minutes before trying again.
1-1440
When the system cannot allocate an object needed to attach a new journal receiver to this journal, it will wait the specified number of minutes before trying again.

Delete receiver delay time (DLTRCVDLY)

If the system cannot allocate an object needed to delete a journal receiver associated with this journal and the journal has DLTRCV(*YES) specified, this parameter specifies the time (in minutes) to be used to delay the next attempt to delete the journal receiver.

10
System waits 10 minutes before trying again.
1-1440
System waits the specified number of minutes before trying again.

Fixed length data (FIXLENDTA)

Specifies the data that is included in the fixed-length portion of the journal entries that are deposited into the attached journal receiver. This parameter is not valid when RCVSIZOPT(*MINFIXLEN) is also specified.

*SAME
The value does not change.
*JOBUSRPGM
The job name, user name and program name will be included in the journal entries deposited into the attached journal receiver.
*JOB
The job name will be included in the journal entries deposited into the attached journal receiver.
*USR
The effective user profile name will be included in the journal entries deposited into the attached journal receiver.
*PGM
The program name will be included in the journal entries deposited into the attached journal receiver.
*PGMLIB
The program library name and the auxiliary storage pool device name that contains the program library will be included in the journal entries deposited into the attached journal receiver.
*SYSSEQ
The system sequence number will be included in the journal entries deposited into the attached journal receiver. The system sequence number gives a relative sequence to all journal entries in all journal receivers on the system.
*RMTADR
If appropriate, the remote address, the address family and the remote port will be included in the journal entries deposited into the attached journal receiver.
*THD
The thread identifier will be included in the journal entries deposited into the attached journal receiver. The thread identifier helps distinguish between multiple threads running in the same job.
*LUW
If appropriate, the logical unit of work identifier will be included in the journal entries deposited into the attached journal receiver. The logical unit of work identifies work related to specific commit cycles.
*XID
If appropriate, the transaction identifier will be included in the journal entries deposited into the attached journal receiver. The transaction identifier identifies transactions related to specific commit cycles.

Journal object limit (JRNOBJLMT)

Specifies the option that affects the maximum number of objects that can be journaled to the journal.

*MAX250K
The maximum number of objects that can be journaled to the journal is 250,000.
*MAX10M
The maximum number of objects that can be journaled to the journal is 10,000,000. Any journal receivers associated with such a journal cannot be saved or restored to any releases prior to V5R4M0 nor can they be replicated via remote journaling to any releases prior to V5R4M0.

Once this value is specified for the journal, the JRNOBJLMT cannot be set to the lower limit.

Runtime performance concerns should be considered when choosing this option. With this new attribute, there is an opportunity for a greater number of objects journaled to one journal. Thus there is a potential opportunity of more objects that can be actively changing at the same time which can affect journal runtime performance. Therefore if the frequency of journal entries being deposited to this one journal is causing runtime performance concerns, then a better alternative would be to split the journaled objects to more than one journal.

Be aware that increasing the quantity of objects associated with a single journal may increase your IPL time, independent ASP vary on time, or disaster recovery time. As a general rule-of-thumb, if the number of actively changing objects is likely to be greater than 5,000 consider journaling some of these objects to a separate journal. The larger the number of actively changing objects for a given journal at system termination, the longer it will take to recover the journal at IPL or vary on of an independent ASP.

Text 'description' (TEXT)

Specifies the text that briefly describes the object.

*BLANK
No text is specified.
'description'
Specify no more than 50 characters of text, enclosed in apostrophes.

Authority (AUT)

Specifies the authority you are giving to users who do not have specific authority for the object, who are not on an authorization list, and whose group profile or supplemental group profiles do not have specific authority for the object.

*LIBCRTAUT
The system determines the authority for the object by using the value specified for the Create authority (CRTAUT) parameter on the Create Library command (CRTLIB) for the library containing the object to be created. If the value specified for the CRTAUT parameter is changed, the new value will not affect any existing objects.
*CHANGE
The user can perform all operations on the object except those limited to the owner or controlled by object existence (*OBJEXIST) and object management (*OBJMGT) authorities. The user can change and perform basic functions on the object. *CHANGE authority provides object operational (*OBJOPR) authority and all data authority. If the object is an authorization list, the user cannot add, change, or remove users.
*ALL
The user can perform all operations except those limited to the owner or controlled by authorization list management (*AUTLMGT) authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the object.
*USE
The user can perform basic operations on the object, such as running a program or reading a file. The user cannot change the object. Use (*USE) authority provides object operational (*OBJOPR), read (*READ), and execute (*EXECUTE) authorities.
*EXCLUDE
The user cannot access the object.
name
Specify the name of an authorization list to be used for authority to the object. Users included in the authorization list are granted authority to the object as specified in the list. The authorization list must exist when the object is created.

Examples

Example 1: Creating a Journal to Use Auxiliary Storage Pool

CRTJRN   JRN(MYLIB/JRNLA)  JRNRCV(MYLIB/RCV01)  ASP(3)

This command creates a journal named JRNLA in library MYLIB. Storage space for the journal is allocated from user auxiliary storage pool (ASP) 3. Journal receiver RCV01 in library MYLIB is attached to journal JRNLA. The public authority for the journal is taken from the CRTAUT parameter for library MYLIB.

Example 2: Creating a Journal with a Larger Object Limit

CRTJRN   JRN(YOURLIB/JRNLB) JRNRCV(YOURLIB/RCV01)
         RCVSIZOPT(*MAXOPT3 *RMVINTENT)
         JRNOBJLMT(*MAX10M)

This command creates a journal named JRNLB in library YOURLIB that will allow up to 10,000,000 objects to be journaled to it. Journal receiver RCV01 in library YOURLIB is attached to journal JRNLB. The public authority for the journal is taken from the CRTAUT parameter for library YOURLIB. Using the larger journal object limit requires that one of the values of maximum options for the receiver size option parameter be specified. In this case, *MAXOPT3 was chosen for the receiver size option parameter. This will allow the journal receiver to grow to approximately one terabye, the sequence number to reach 18,446,744,073,709,551,600 and a maximum journal entry size of 4,000,000,000 bytes. Entries needed soley for recovery purposes will be removed when they are no longer needed by the system.

Error messages

*ESCAPE Messages

CPF70A0
FIXLENDTA parameter not allowed.
CPF70A1
FIXLENDTA parameter not allowed with RCVSIZOPT(*MINFIXLEN).
CPF70B5
JRNOBJLMT(&1) not allowed.
CPF70B8
MINENTDTA values specified not allowed.
CPF70E0
Operation on &1 not allowed.
CPF70E2
DLTRCV(*YES) not allowed.
CPF70E5
RCVSIZOPT values specified not allowed.
CPF70F1
Journal receiver threshold too big for journal.
CPF70F5
Receiver threshold value is not valid.
CPF7003
Entry not journaled to journal &1. Reason code &3.
CPF701A
Journal receiver not eligible for operation.
CPF7010
Object &1 in &2 type *&3 already exists.
CPF7011
Not enough storage or resources.
CPF7012
Auxiliary storage pool &4 not found for object &1.
CPF7015
Error on JRNRCV specifications.
CPF7017
Library QTEMP not valid for message queue parameter.
CPF704E
RCVSIZOPT(*MINFIXLEN) not allowed.
CPF708A
Journal QAUDJRN in QSYS not created or restored.
CPF708D
Journal receiver found logically damaged.
CPF708E
Journal receiver not allowed with *MAXOPT1 or *MAXOPT2 or *MAXOPT3.
CPF709F
Start of journal caching not allowed. Reason code &3.
CPF9801
Object &2 in library &3 not found.
CPF9802
Not authorized to object &2 in &3.
CPF9803
Cannot allocate object &2 in library &3.
CPF9806
Cannot perform function for object &2 in library &3.
CPF9810
Library &1 not found.
CPF9820
Not authorized to use library &1.
CPF9825
Not authorized to device &1.
CPF9830
Cannot assign library &1.
CPF9839
Object &1 not created.
CPF9840
Object &1 not created.
CPF9873
ASP status is preventing access to object.
CPF9875
Resources exceeded on ASP &1. Press HELP.