Start Journal Library (STRJRNLIB)

Where allowed to run: All environments (*ALL)
Threadsafe: Conditional

The Start Journal Library (STRJRNLIB) command is used to start journaling changes (made to a library or list of libraries) to a specific journal, and optionally to start journaling changes to objects within the library or list of libraries. Objects created in, moved into, or restored into a journaled library may be automatically journaled to the same journal the library is journaled to. For more information about journal entries which can be sent, see the Journal management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/. Search for "journal entry finder".

After journaling begins for the object, the user should save the journaled object to preserve its journal attribute information. Also, the object must be saved because, for example, journaled changes cannot be applied to a version of the object that was saved before journaling was in effect.

Objects created, moved, or restored into the library that are eligible for journaling may automatically start journaling to the same journal as the library. Which objects inherit the journal state of the library and what journaling attributes they start journaling with are determined by the inherit journaling attributes of the library.

Use the Display Library Description (DSPLIBD) command to display journal information including the inherit rules for the library.

For other ways to start journaling see the following commands:

Access paths - Start Journal Access Path (STRJRNAP)
Integrated file system objects - Start Journal (STRJRN)
Physical files - Start Journal Physical File (STRJRNPF)
Other objects - Start Journal Object (STRJRNOBJ)

Restrictions:

The object must not be journaling changes to another journal.
The maximum number of objects that can be associated with one journal is either 250,000 or 10,000,000. To get 10,000,000, the value of *MAX10M must have been specified for the JRNOBJLMT parameter on either the Create Journal (CRTJRN) command or on the Change Journal (CHGJRN) command. Once the number of objects is greater than or equal to this maximum, journaling does not start for any more objects.
The specified journal must be a local journal. Although all object types which can be journaled to a local journal can also have their changes sent to a remote journal, this is accomplished by a two step process. First start journaling to the local journal. Then connect the local journal to a remote instance. To initiate such a connection, use the Add Remote Journal (ADDRMTJRN) command or the Add Remote Journal (QjoAddRemoteJournal) API. For information about remote journaling, see the Journal management topic collection in the IBM i Information Center at http://www.ibm.com/systems/i/infocenter/.
The specified journal and object must reside in the same auxiliary storage pool (ASP).
If the specified library contains a data area named QDFTJRN, no objects being created, moved, or restored into the library will inherit the journaling state of the library. Instead, objects will automatically start journaling based on the contents of the QDFTJRN data area. When the QDFTJRN data area is deleted, objects being created, moved, and restored into the library will inherit the journaling state of the library based on the inherit rules.
The following libraries may not be journaled: QSYS, QSYSxxxxx, QSYS2, QSYS2xxxxx, QPTFOBJ1, QPTFOBJ2, QRECOVERY, QRCYxxxxx, QSPL, QSPLxxxxx, QRCL, QRCLxxxxx, QRPLOBJ, QRPLxxxxx, QGPL, QTEMP, SYSIBM, SYSIBxxxxx, SYSIBMADM, SYSPROC, and SYSTOOLS, where xxxxx is a five-digit number of an Independent Auxiliary Storage Pool (IASP).
Lock Processing
The library to start journaling is locked with a read exclusive lock (*EXCLRD).

Top

Parameters

Keyword	Description	Choices	Notes
LIB	Library	Values (up to 300 repetitions): Generic name, name	Required, Positional 1
JRN	Journal	Qualified object name	Required, Positional 2
	Qualifier 1: Journal	Name
	Qualifier 2: Library	Name, LIBL, CURLIB
INHRULES	Inherit rules	Values (up to 20 repetitions): Element list	Optional
	Element 1: Object type	ALL, FILE, DTAARA, DTAQ
	Element 2: Operation	ALLOPR, CREATE, MOVE, RESTORE, *RSTOVRJRN
	Element 3: Rule action	INCLUDE, OMIT
	Element 4: Images	OBJDFT, AFTER, *BOTH
	Element 5: Omit journal entry	OBJDFT, NONE, *OPNCLO
	Element 6: Remote journal filter	OBJDFT, NO, *YES
	Element 7: Name filter	Generic name, name, *ALL
LOGLVL	Logging level	ERRORS, ALL	Optional

Top

Library (LIB)

Specifies a maximum of 300 library names for which changes are to be journaled.

generic-name: Specify the generic name of the library for which changes are to be journaled. A generic name is a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, all libraries that have names with the same prefix as the generic name will have their changes journaled.
library-name: Specify the name of the library for which changes are to be journaled.

Top

Journal (JRN)

Specifies the journal that receives the journaled changes.

This is a required parameter.

Qualifier 1: Journal

journal-name: Specify the name of the journal that receives the journaled changes.

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, QGPL is used.
library-name: Specify the name of the library to be searched.

Top

Inherit rules (INHRULES)

Specifies which objects created within a journaled library, moved into a journaled library, or restored into a journaled library should inherit the journal state of the library and which journaling attributes those objects should have.

Each rule defines object types, object names, and operations that the rule applies to. Multiple rules can be defined for the same set of objects. If multiple rules are defined for the same object and operation, the last rule defined for that object will be applied.

These rules only affect objects when they are created, moved into, or restored into the library. The journaling state and journaling attributes of objects within the library do not change if they are renamed. Once journaled, objects will not automatically end journaling if they are moved out of the library. Additionally, objects that are journaled prior to being moved into the library will not change their journaling state or attributes when they are moved.

Note: If a data area named QDFTJRN exists within the library, no objects created, moved, or restored into the library will inherit the journal state of the library. Objects created, moved, and restored into the library will automatically start journaling based on the data area information.

Element 1: Object type

Specify the object type of the objects that are identified by this rule.

*ALL: This rule applies to all object types that can be journaled.
*DTAARA: This rule applies to data areas.
*DTAQ: This rule applies to data queues.
*FILE: This rule applies to database physical files.

Element 2: Operation

Specifies the operation or operations identified by this rule.

*ALLOPR: This rule applies to all objects created in, moved into, or restored into the library. This is a combination of the values *CREATE, *MOVE, and *RESTORE. See their descriptions for further information.
*CREATE: This rule applies to all objects created in the library.
*MOVE: This rule applies to all objects moved into the library, if they are not already journaled.
*RESTORE: This rule applies to all objects restored into the library. If an object is restored over a currently existing object, the restored object will retain the same journal state and journaling attributes of the object it was restored over. If an object was never journaled when it was saved, journaling is started for the object when it is restored into the library. Otherwise, if an object was journaled when it was saved, it will first attempt to start journaling to the journal it was journaled to when it was saved, with the same journaling attributes it had when it was saved. If that journal does not exist, the object will start journaling to the same journal the library is journaled to, with the journaling attributes defined by this rule. A rule with *RESTORE specified will override any previous rule for the same object type with *RSTOVRJRN specified.
If the accompanying rule action is set to *OMIT and the object is not restored over an existing object, the restored object will retain the same journal state and journaling attributes as it had when it was saved. The journal state of the library is ignored.
*RSTOVRJRN: This rule applies to all objects restored into the library. If an object is restored over a currently existing object, the restored object will retain the same journal state and journaling attributes of the object it was restored over. Otherwise, the object will start journaling to the same journal the library is journaled to, with the journaling attributes defined by this rule. A rule with *RSTOVRJRN specified will override any previous rule for the same object type with *RESTORE specified.
If the accompanying rule action is set to *OMIT and the object is not restored over an existing object, the restored object will retain the same journal state and journaling attributes as it had when it was saved. The journal state of the library is ignored.

Element 3: Rule action

Specifies whether or not the objects that match object type and operation in this rule will be included or omitted from the list of objects that inherit the journal state of the library.

*INCLUDE: All objects that match the object type and operation will inherit the journal state of the library, and will use the journaling attributes defined by this rule.
*OMIT: All objects that match object type and operation will not inherit the journal state of the library. This overrides an *INCLUDE specification and is intended to be used to omit a subset of a previously defined rule.

Element 4: Images

Specifies the kinds of images that are written to the journal receiver for changes to objects that inherit the journal state of the library.

Note: This element is ignored if *OMIT is specified for Rule action.

*OBJDFT: The default value for each object type will be used for this journaling attribute when an object inherits the journal state of the library. Database files (*FILE) will have both before and after images generated by the system (*BOTH). All other object types will have only after images generated by the system (*AFTER).
*AFTER: Only after images are generated for objects that inherit the journal state of the library.
*BOTH: Both before and after images are generated for objects that inherit the journal state of the library.
Note: The value *BOTH is only valid for data area (*DTAARA) and database file (*FILE) objects. If *BOTH is specified and *ALL is specified for Object type, the system will generate both before and after images for data areas and database files. All other object types will only generate after images.

Element 5: Omit journal entry

Specifies the journal entries that are omitted for objects that inherit the journal state of the library.

Note: This element is ignored if *OMIT is specified for Rule action.

*OBJDFT: The default value for each object type will be used for this journaling attribute when an object inherits the journal state of the library. Database files (*FILE) will omit open and close entries. No other object types will omit journal entries.
*NONE: No journal entries will be omitted for objects that inherit the journal state of the library.
*OPNCLO: Open and close entries are omitted for database file (*FILE) objects that inherit the journal state of the library. This prevents the use of TOJOBO and TOJOBC entries on the Apply Journaled Changes (APYJRNCHG) command, but it saves some storage space in the journal receivers.
Note: The value *OPNCLO is only valid for database files (*FILE). If *OPNCLO is specified and *ALL is specified for Object type, database files will omit open and close entries. All other object types will not omit any journal entries.

Element 6: Remote journal filter

Specifies whether or not the journal entries deposited for the objects that inherit the journal state of the library should be eligible for remote journal filtering by object.

See the Change Remote Journal (CHGRMTJRN) command or the Change Journal State (QjoChangeJournalState) API for more information about remote journal filtering.

Note: This element is ignored if *OMIT is specified for Rule action.

*OBJDFT: The default value for each object type will be used for this journaling attribute when an object inherits the journal state of the library. For all object types, journal entries deposited for the objects that inherit the journal state of the library will not be eligible for remote journal filtering by object.
*NO: Journal entries deposited for the objects that inherit the journal state of the library will not be eligible for remote journal filtering by object.
*YES: Journal entries deposited for the objects that inherit the journal state of the library will be eligible for remote journal filtering by object. When using remote journal filtering by object, journal entries for the object will not be sent to the target system.

Element 7: Name filter

Specifies the object names of the objects that are identified by this rule.

*ALL: This rule applies to all objects that match the other criteria.
name: This rule applies to all objects that match the other criteria and match the specified name.
generic-name: This rule applies to all objects that match the other criteria and match the specified generic name.
Note: A generic name is specified as a character string that contains one or more characters followed by an asterisk (*). If a generic name is specified, then all objects that have names with the same prefix as the generic object name are selected.

Top

Logging level (LOGLVL)

Specifies the error logging level used. This parameter is used to determine which messages will be sent.

*ERRORS: All diagnostic and escape messages are sent but the command will not send successful completion messages for each object. At the completion of this command, one completion message will be sent.
*ALL: The command sends all the messages that would be sent with *ERRORS and it will also send the successful completion message for each object.

Top

Examples

Example 1: Start Journaling a Single Library

STRJRNLIB  LIB(MYLIBA) JRN(MYLIBA/JRN)

This command journals all changes to library MYLIBA to journal JRN in MYLIBA. Also, all objects that can be journaled that are created in, moved into, or restored into this library will automatically start journaling to journal JRN in MYLIBA.

Example 2: Start Journaling a Library and Selectively Inherit Journaling

STRJRNLIB LIB(MYLIBC) JRN(MYLIBC/JRN)
          INHRULES((*FILE *ALLOPR *INCLUDE *BOTH *OPNCLOSYN)
                   (*DTAARA *CREATE *INCLUDE *OBJDFT *OBJDFT))

This command journals all changes to library MYLIBC to journal JRN in MYLIBC. All files that are created in, moved into, or restored into library MYLIBC will have journaling started to journal JRN in library MYLIBC, and will generate both before and after images and will omit open and close entries. All data areas that are created in library MYLIBC will have journaling started.

Example 3: Start Journaling a Library and Selectively Inherit Journaling with Omit

STRJRNLIB LIB(MYLIBD) JRN(MYLIBA/JRN)
          INHRULES((*ALL *ALLOPR *INCLUDE *OBJDFT *OBJDFT
                    *OBJDFT)
                   (*FILE *CREATE *OMIT)
                   (*FILE *RESTORE *OMIT))

This command journals all changes to library MYLIBD to journal JRN in MYLIBA. All objects that can be journaled that are created in, moved into, or restored into library MYLIBD will have journaling started to journal JRN in MYLIBA, except any files that are created or restored into the library.

Example 4: Start Journaling a Library and Selectively Inherit Journaling with Omit and Name Filtering

STRJRNLIB LIB(MYLIBD) JRN(MYLIBA/JRN)
          INHRULES((*ALL *ALLOPR *INCLUDE *OBJDFT *OBJDFT
                    *OBJDFT *ALL)
                   (*FILE *ALLOPR *OMIT *OBJDFT *OBJDFT
                    *OBJDFT W*))

Top

Error messages

*ESCAPE Messages

CPF6979: Journal &1 in library &2 is unusable.
CPF700A: &1 of &2 objects have started journaling.
CPF705A: Operation failed due to remote journal.
CPF9801: Object &2 in library &3 not found.
CPF9802: Not authorized to object &2 in &3.
CPF9803: Cannot allocate 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.
CPF9873: ASP status is preventing access to object.
CPF9875: Resources exceeded on ASP &1. Press HELP.

Top