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:

A journal cannot be created in the library QTEMP.
The receiver specified must be created before issuing this command and it must be empty (that is, the receiver must not have been previously attached to a journal or have been in the process of being attached to a journal).
This command cannot be used to create a remote journal. See the ADDRMTJRN (Add Remote Journal) command description or the Add Remote Journal (QjoAddRemoteJournal) API in the System API Reference information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
If one of the *MAXOPT values from the RCVSIZOPT parameter is not to be in effect for the journal, the maximum threshold value that can be specified for any journal receiver being attached is 1,919,999 kilobytes.
If the library to contain the journal is on an independent ASP then the journal receiver specified must be located on an independent ASP that is in the same ASP group as the journal's library. Likewise, if the library to contain the journal is not on an independent ASP, then the journal receiver specified cannot be located on an independent ASP.
If the library to contain the journal is on an independent ASP then ASP(*LIBASP) must be specified.
RCVSIZOPT(*MINFIXLEN) and FIXLENDTA cannot be used for the system security audit journal QSYS/QAUDJRN. Journal entries in the security audit journal are required to contain all possible data that could be used for auditing purposes.
JRNOBJLMT(*MAX10M) is only valid if one of the *MAXOPT values was specified for the RCVSIZOPT parameter.
JRNOBJLMT(*MAX10M), once specified for a journal, cannot be changed.

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

Top

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:

When an attached journal receiver's threshold is surpassed, the message CPF7099 is sent if the journal has the MNGRCV(*USER) attribute.
When an attached journal receiver's threshold is surpassed, the system attempts to create and attach a new receiver if the journal has the MNGRCV(*SYSTEM) attribute. When the old receiver is detached, the message CPF7020 is sent. If the attempt fails due to lock conflicts, the system sends the message CPI70E5 and then tries again every ten minutes (or as often as requested via the MNGRCVDLY parameter) until the change journal operation is successful. If the change journal fails for any other reason, message CPI70E3 is sent.
When a journal receiver's sequence number exceeds 2,147,000,000, the message CPI70E7 is sent. If the journal receiver was attached while RCVSIZOPT(*MAXOPT1 or *MAXOPT2) was in effect for the journal, message CPI70E7 is sent when the sequence number exceeds 9,900,000,000. If the journal receiver was attached while RCVSIZOPT(*MAXOPT3) was in effect for the journal, message CPI70E7 is sent when the sequence number exceeds 18,446,644,000,000,000,000.
When the system cannot determine if the journal has the MNGRCV(*SYSTEM) attribute, or if the attempt to create and attach a new journal receiver fails because of something other than a lock conflict, the message CPI70E3 is sent.
When remote journal operations occur, see the Journal Management information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
When the system cannot delete a receiver due to a lock conflict, an exit program indicating that the receiver cannot be deleted, or the receiver is not yet fully replicated to all remote journals, CPI70E6 is sent and the operation will be retried every 10 minutes (or as often as requested via the DLTRCVDLY parameter). If a delete fails for any other reason, CPI70E1 is sent.

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.

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.

Notes:

The journal receiver threshold value must be specified with a value other than *NONE before this value is specified.
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 to the journal message queue, 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.

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 information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/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.

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.

*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.

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.