RPGIV @ Work

A unique site for RPG and System i Lovers

Welcome!

Hi, this site will provide all what you need in System i and RPG developments.

My Name is Chamara Withanachchi, System i Expert and RPG Developer. And in the field for last 11 years.

I hope you will find lot of valuable information from this site

Start Journal (QjoStartJournal) API Print E-mail
User Rating: / 3
PoorBest 
Written by Chamara Withanachchi   

 Required Parameter Group:

1 Object entry array Input Char(*)
2 File ID entry array Input Char(*)
3 Journal Input Char(*)

 Omissible Parameter Group:
4 Start journal options Input Char(*)
5 Error code I/O Char(*)


 Service Program Name: QJOURNAL

 Default Public Authority: *USE

 Threadsafe: Yes

The Start Journal (QjoStartJournal) API is used to start journaling changes (made to an object or list of objects) to a specific journal. The object types that are supported through this API are Data Areas (*DTAARA), Data Queues (*DTAQ), Byte Stream Files (*STMF), Directories (*DIR), and Symbolic Links (*SYMLNK). For objects of type *STMF, *DIR, or *SYMLNK, only objects in the Root ('/'), QOpenSys, and User-defined file systems are supported. For more information about the possible journal entries that can be sent.

After journaling begins for the object, the user should save the journaled objects. The objects 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.

Note: Other ways to start journaling,

  • Integrated File System objects - Start Journal (STRJRN)
  • Access Paths - Start Journal Access Path (STRJRNAP)
  • Data Areas and Data Queues - Start Journal Object (STRJRNOBJ)
  • Physical Files - Start Journal Physical File (STRJRNPF)

Restrictions:

  1. The object must not be journaling changes to another journal.
  2. The maximum number of objects that can be associated with one journal is 250,000. This maximum number includes objects whose changes are currently being journaled, and journal receivers that are associated with the journal. If the number of objects is larger than this maximum number, journaling does not start.
  3. 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.
  4. The specified journal and object must reside in the same Auxiliary Storage Pool (ASP).
  5. Byte stream files that are currently memory mapped or byte stream files that are being used as IXS network storage spaces cannot be journaled.
  6. Objects that are internally marked as not eligible for journaling cannot be journaled. The system may mark system working directories that are created inside of user directories as not eligible for journaling.
  7. For data areas, only local external data area objects may be journaled. The special data areas (*LDA, *GDA, *PDA) and DDM data areas cannot be journaled.
  8. For data queues, only local data queues are supported. DDM data queues cannot be journaled.
  9. At least one of parameter object entry or file ID entry must not be NULL.

Authorities and Locks

Journal Authority
*OBJOPR, *OBJMGT
Non-IFS Object Authority (if specified)
*OBJOPR, *READ, *OBJMGT
IFS Object Authority (if specified)
*R, *OBJMGT (also *X if object is a directory and *ALL is specified for the directory subtree key)
Directory Authority (for each directory preceding the last component in the path name)
*X
Journal Lock
*SHRUPD
Non-IFS Object Lock (if specified)
*SHRUPD
IFS Object Lock (if specified)
O_RDONLY | O_SHARE_RDWR

Required Parameters

Object entry array
INPUT; CHAR(*)

The path name of the object for which changes are to be journaled.

If this parameter is NULL, the file ID entry must not be NULL.

The object entry must be in the following format.

Object Entry Format

Offset Type Field
Dec Hex
0 0 BINARY(4) Number in array
4 4 CHAR(12) Reserved
Note:These fields repeat for each object path name.
16 10 BINARY(4) Length of this object path name entry
20 14 CHAR(10) Include or omit
30 1E CHAR(2) Reserved
32 20 PTR(16) Pointer to an object path name

Number in array. The number of objects in the object entry array. The possible values are 1 through 300.

Length of this object path name entry. The length of the current object path name entry that can be used as the displacement from the start of this path name entry to the next path name entry. The length must be a minimum of 32 bytes and must be a multiple of 16.

Include or omit. Whether the path name is included or omitted from the start journal operation.

*INCLUDE Objects that match the object name path are to be journaled, unless overridden by an *OMIT specification.
*OMIT Objects that match the object name path are not to be journaled. This overrides any *INCLUDE specification and is intended to be used to omit a subset of a previously selected path.

Pointer to an object path name. A pointer to the object path name for which changes are to be journaled. All relative path names are relative to the current directory at the time of the call to QjoStartJournal.

In the last component of the path name, an asterisk (*) or a question mark (?) can be used to search for patterns of names. The * tells the system to search for names that have any number of characters in the position of the * character. The ? tells the system to search for names that have a single character in the position of the ? character. Symbolic links within the path name will not be followed. If the path name begins with the tilde (~) character, then the path is assumed to be relative to the appropriate home directory.

The pointer given points to a path name structure. If that path name structure contains a pointer, it must be 16-byte aligned. If not, unpredictable results may occur.

Reserved. A reserved field that must be set to hexadecimal zeros.

File ID entry array
INPUT; CHAR(*)

The object file identifiers (FID) for which changes are to be journaled.

If this parameter is NULL, the object entry parameter must not be NULL.

The structure of this parameter follows.

Object Identifier Array Format

Offset Type Field
Dec Hex
0 0 BINARY(4) Number in array
4 4 CHAR(12) Reserved
Note: These fields repeat for each file identifier.
16 10 CHAR(16) Object file identifier

Number in array. The number of objects in the object file identifier list. The possible values are 1 through 300.

Reserved. A reserved field that must be set to hexadecimal zeros.

Object file identifier. The unique 16-byte file identifier (FID) associated with integrated file system related objects.

Journal
INPUT; CHAR(*)

The path name of the journal that receives the journal entries. All relative path names are relative to the current directory at the time of the call to QjoStartJournal.

If a pointer is specified in the path name of the journal, it must be 16-byte aligned. If not, unpredictable results may occur.


Omissible Parameters

Start journal options
INPUT; CHAR(*)

The start journal options, if any, to use for the selection of objects to start journaling changes and how those changes should be journaled. If this parameter is not specified, objects will be journaled using the default actions described in the field descriptions of the valid keys. See Keys for the list of valid keys.

This parameter must be specified, but may be a NULL pointer.

You may specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.

Each option record must be 16-byte aligned. If not, unpredictable results may occur.

The information must be in the following format:

Journal Options Format

Offset Type Field
Dec Hex
0 0 BINARY(4) Number of option records
4 4 CHAR(12) Reserved
Note:These fields repeat for each option record.
16 10 BINARY(4) Length of option record
20 14 BINARY(4) Key
24 18 BINARY(4) Length of data
28 1C CHAR(4) Reserved
32 20 CHAR(*) Data

Number of option records. The total number of all option records. If this field is zero, an error will be returned.

Length of option record. The length of the option record. This length is used to calculate the starting position of the next option record. If you specify a length of option record that is not equal to the key field's required option record length, an error message will be returned.

Key. Specific action for start journal. See Keys for the list of valid keys.

Length of data. The length of the option record. This length is used to calculate the ending position of the data for this option.

If you specify a length of data that is not equal to the key field's required data length, an error message will be returned.

Reserved. A reserved field that must be set to hexadecimal zeros.

Data. The data that is used to determine the journal option. All values are validity checked.

Error code
I/O; CHAR(*)

The structure in which to return error information. If this parameter is omitted, diagnostic and escape messages are issued to the application.


Keys

The following table lists the valid keys for the key field area of the journal options record. For detailed descriptions of the keys, see the Field Descriptions.

Key Input Type Field Length of
Option
Record
Length
of Data
STRJRN Command Parameter
1 CHAR(5) Directory Subtree 32 5 SUBTREE
2 CHAR(48) Name Pattern 64 48 PATTERN
3 CHAR(4) New objects inherit journaling 32 4 INHERIT
4 CHAR(6) Images 32 6 IMAGES
5 CHAR(10) Omit journal entry 32 10 OMTJRNE

Field Descriptions

Directory subtree. Whether the directory subtrees are included in the start journal operation. The default is *NONE.

Note: This parameter is ignored if the object entry parameter is not specified or if the object is not a directory.

*NONE Only the objects that match the selection criteria are processed. The objects within selected directories are not processed implicitly.

*ALL All objects that meet the selection criteria are processed in addition to the entire subtree of each directory that matches the selection criteria. The subtree includes all subdirectories and the objects within those subdirectories.

Name pattern. The patterns to be used to include or omit objects for the start journal operation. The default will be to include all patterns that match.

Note: This parameter is ignored if the object entry parameter is not specified.

Name Pattern Format

Offset Type Field
Dec Hex
0 0 BINARY(4) Number in array
8 8 CHAR(12) Reserved
Note: These fields repeat for each name pattern.
16 10 BINARY(4) Length of this pattern entry
20 14 CHAR(10) Include or omit
30 1E CHAR(2) Reserved
32 20 PTR(16) Pointer to pattern path structure

Number in array. The number of patterns in the pattern list. The possible values are 1 through 20.

Reserved. A reserved field that must be set to hexadecimal zeros.

Length of this pattern entry. The length of this pattern entry. It is used to calculate the position of the next pattern entry. This must be set to 32.

Include or omit. Whether the name pattern is included or omitted from the start journal operation.

*INCLUDE Objects that match the object name pattern are to be journaled, unless overridden by an *OMIT specification.

*OMIT Objects that match the object name pattern are not to be journaled. This overrides an *INCLUDE specification and is intended to be used to omit a subset of a previously selected pattern.

Pointer to pattern path structure. A pointer to a path structure.

This pointer must be 16-byte aligned. If not, unpredictable results may occur.

New objects inherit journaling. Whether new objects created in an object can inherit the journaling options and the journal state of the parent directory. If the new objects inherit journaling parameter is not specified, the default will be to not inherit journaling options and the journal state of the parent directory.

*NO New objects created within a directory will not inherit the journaling options and journal state of the parent directory.

*YES New objects created within a directory will inherit the journaling options and journal state of the parent directory.

Images. The kinds of images that are written to the journal receiver for updates to objects. The value *BOTH is only supported for objects of type *DTAARA.

If the images parameter is not specified, the default value will be *AFTER.

*AFTER Only after images are generated for changes to the objects.

*BOTH The system generates both before and after images for changes to the objects.

Omit journal entry. The journal entries that are omitted. This parameter only supports objects of type *STMF, *DIR, or *SYMLNK that are in the Root ('/'), QOpenSys, and user-defined file systems. If the omit journal entry parameter is not specified, the default will be *NONE.

*NONE No entries are omitted.

*OPNCLOSYN Open, close, and force operations on the specified objects do not generate open, close, and force journal entries. This prevents the use of TOJOBO and TOJOBC entries on the Apply Journal Changes (APYJRNCHG) command, but it saves some storage space in the journal receivers.

Error Messages

The following messages may be sent from this API:

Message ID Error Message Text
CPFA0D4 E File system error occurred.
CPF6979 E Journal is unusable.
CPF700A E &1 of &2 objects started journaling.
CPF70EF E Parameters cannot be used together.
CPF705A E Operation failed due to remote journal.
CPF9801 E Object &2 in library &3 not found.
CPF9802 E Not authorized to object &2 in &3.
CPF9803 E Cannot allocate object &2 in library &3.
CPF9810 E Library &1 not found.
CPF9820 E Not authorized to use library &1.
CPF9830 E Cannot assign library &1.

<Previous   Next>