Start Journal (QjoStartJournal) API

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, see the Journal management topic.

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: For other ways to start journaling, see the following commands in the Control Language (CL) information:

• 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 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. This maximum number includes objects whose changes are currently being journaled, objects for which journaling was ended while the current receiver was attached, and journal receivers that were associated with the journal while the current receiver was attached. 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. For information about remote journaling, see the Journal management topic.
4. The specified journal and object must reside in the same Auxiliary Storage Pool (ASP).
5. Byte stream files that are currently memory mapped, are virtual volume files, or 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.

Additional information about path name patterns is in the Integrated file system information in the Files and file systems topic.

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.

For more information on the path name format, see Path name format.

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.

For more information on the journal path name format, see Path name format.

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. For the format of the structure, see Error Code Parameter. 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.

Some messages for this API refer to parameters and values for the Start Journal (STRJRN) command. This table also can be used to locate the key names that correspond to the STRJRN command parameters.

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.

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.

Additional information about path name patterns is in the Integrated file system information in the Files and file systems topic.

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

Name Pattern Format

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.

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

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

For more information on the pattern path name format, see Path name format.

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.

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.

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.

Error Messages

The following messages may be sent from this API:

Example

See Code disclaimer information for information pertaining to code examples.

The following example starts journaling a directory object and all objects within that directory subtree. Additionally, it starts journaling on another object identified by its file ID.

#include <string.h>
#include <qjournal.h>

void main()
{
    Qjo_Object_Entry_Array_t objectEntryArray;
    Qjo_File_ID_Entry_Array_t fileIDEntryArray;

    struct PathNameStruct
    {
        Qlg_Path_Name_T header;
        char p[50];
    };

    struct PathNameStruct path;
    struct PathNameStruct journalPath;

    char pathName[] = "/CustomerData";
    char jrnPathName[] = "/QSYS.LIB/ADMIN.LIB/CUSTDATA.JRN";

    Qp0lFID_t fileID;

    struct JournalOptionsStruct
    {
        Qjo_Journal_Options_t     opts;
        char spaceForAdditionalOptions[200];
    };

    struct JournalOptionsStruct journalOptions;
    Qjo_Option_t *optionP;

    Qus_EC_t                  errorCode;


    /* Setup the object's path name structure.                */
    memset(&path, 0, sizeof(path));
    path.header.CCSID = 37;
    memcpy(path.header.Country_ID,"US",2);
    memcpy(path.header.Language_ID,"ENU",3);
    path.header.Path_Type = QLG_CHAR_SINGLE;
    path.header.Path_Length = strlen(pathName);
    path.header.Path_Name_Delimiter[0] = '/';
    memcpy(path.p, pathName, path.header.Path_Length);

    /* Setup the object entry array.                         */
    memset(&objectEntryArray,0,sizeof(objectEntryArray));
    objectEntryArray.Number_In_Array = 1;

    objectEntryArray.Entry[0].Length_Of_Object_Entry =
      sizeof(objectEntryArray.Entry[0]);
    memcpy(objectEntryArray.Entry[0].Include_Or_Omit,
           QJO_INC_ENT_INCLUDE,
           sizeof(objectEntryArray.Entry[0].Include_Or_Omit));
    objectEntryArray.Entry[0].Path_Name =
      (Qlg_Path_Name_T *)&path;

    /* Get an object's file ID.
       This example is not including the retrieval of the
       file ID for an object.  The user can see the
       Qp0lGetAttr API for information on retrieving an
       object's file ID.  This example will proceed as if the
       fileID variable is set to a valid file ID.            */

    /* Setup the file ID entry array.                        */
    memset(&fileIDEntryArray,0,sizeof(fileIDEntryArray));
    fileIDEntryArray.Number_In_Array = 1;
    memcpy(&fileIDEntryArray.Entry,
           fileID,
           sizeof(fileIDEntryArray.Entry));


    /* Setup the journal's path name structure.              */
    memset(&journalPath, 0, sizeof(journalPath));
    journalPath.header.CCSID = 37;
    memcpy(journalPath.header.Country_ID,"US",2);
    memcpy(journalPath.header.Language_ID,"ENU",3);
    journalPath.header.Path_Type = QLG_CHAR_SINGLE;
    journalPath.header.Path_Length = strlen(jrnPathName);
    journalPath.header.Path_Name_Delimiter[0] = '/';
    memcpy(journalPath.p,
           jrnPathName,
           journalPath.header.Path_Length);

    /* Set the journal options.                              */
    memset(&journalOptions,0,sizeof(journalOptions));
    journalOptions.opts.Number_Of_Options = 3;

    /* Set the *AFTER images key.                            */
    optionP = (Qjo_Option_t *)&journalOptions.opts.Option[0];

    optionP->Length_Of_Record = QJO_KEY_MINIMUM_RECORD_LENGTH;
    optionP->Key = QJO_KEY_IMAGES;
    optionP->Length_Of_Data = QJO_KEY_IMAGES_LENGTH;
    memcpy(optionP->Data,
           QJO_IMAGES_AFTER,
           QJO_KEY_IMAGES_LENGTH);

    /* Set the inherit directory journaling attributes key.  */
    optionP = (Qjo_Option_t *)((char *)optionP +
                               optionP->Length_Of_Record);

    optionP->Length_Of_Record = QJO_KEY_MINIMUM_RECORD_LENGTH;
    optionP->Key = QJO_KEY_INHERIT;
    optionP->Length_Of_Data = QJO_KEY_INHERIT_LENGTH;
    memcpy(optionP->Data,
           QJO_INHERIT_YES,
           QJO_KEY_INHERIT_LENGTH);

    /* Set the subtree processing images key.                */
    optionP = (Qjo_Option_t *)((char *)optionP +
                               optionP->Length_Of_Record);

    optionP->Length_Of_Record = QJO_KEY_MINIMUM_RECORD_LENGTH;
    optionP->Key = QJO_KEY_SUBTREE;
    optionP->Length_Of_Data = QJO_KEY_SUBTREE_LENGTH;
    memcpy(optionP->Data,
           QJO_SUBTREE_ALL,
           QJO_KEY_SUBTREE_LENGTH);

    /* Setup the error code structure to cause an exception
       to be sent upon error.                                */
    memset(&errorCode,0,sizeof(errorCode));
    errorCode.Bytes_Provided = 0;

    QjoStartJournal(&objectEntryArray,
                    &fileIDEntryArray,
                    (Qlg_Path_Name_T *)&journalPath,
                    (Qjo_Journal_Options_t *)&journalOptions,
                    &errorCode);
}