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 APIs topic collection in the Programming category in the IBM i Information Center at http://www.ibm.com/systems/i/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

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 topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/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.

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.