End Journal (QjoEndJournal) API

The End Journal (QjoEndJournal) API is used to end journaling changes (made to an object or list of objects) to a specific journal. All objects of object type *DIR, *STMF, *SYMLNK, *DTAARA or *DTAQ that currently are being journaled to a specific journal also may have journaling stopped. For objects of type *STMF, *DIR or *SYMLNK, only objects in the Root ('/'), QOpensys, and user-defined file systems are supported.

Note: For other ways to end journaling, see the following commands in the Control Language (CL) information:

• Integrated File System objects - End Journal (ENDJRN)
• Access Paths - End Journal Access Path (ENDJRNAP)
• Data Areas and Data Queues - End Journal Object (ENDJRNOBJ)
• Physical Files - End Journal Physical File (ENDJRNPF)

Restrictions:

1. Objects specified on the API cannot be in use for any reason at the time the API is running.
2. If a journal name and a list of object names are specified, all objects currently must be journaled to the indicated journal.
3. At least one of parameter object entry or file ID entry must not be NULL.
4. The specified journal must be a local journal.

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

*EXCLRD

Non-IFS Object Lock (if specified)

*EXCL

IFS Object Lock (if specified)

O_RDONLY | O_SHARE_NONE

Required Parameters

Object entry

INPUT; CHAR(*)

The path name of the object for which changes are no longer to be journaled. If the object path contains *ALL, all objects supported by this API that currently are being journaled to the indicated journal are to stop having their changes journaled. If the object path is *ALL, then the file ID entry must be NULL.

If this parameter is NULL, the file ID entry parameter 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 path name entry
20	14	CHAR(10)	Include or omit
30	1E	CHAR(2)	Reserved
32	20	CHAR(*)	Object path name

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

Length of this path name entry. The length of the current 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 end journal operation. If the object path is *ALL, then the include or omit paramter is ignored.

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

Object path name. The object path name for which changes are no longer to be journaled. All relative path names are relative to the current directory at the time of the call to QjoEndJournal.

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.

If a pointer is specified in the object path name, 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

INPUT; CHAR(*)

File identifiers (FID) for which changes are no longer to be journaled.

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

The structure of this parameter follows.

Object Identifier 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.
4	4	CHAR(16)	File Identifier

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

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

Omissible Parameters

Journal

INPUT; CHAR(*)

The path name of the journal to which changes currently are being journaled. All relative path names are relative to the current directory at the time of the call to QjoEndJournal.

If the journal path name entry contains *OBJ, the path name of the journal is determined by the system from the specified object path name or object file identifier.

If the journal parameter is NULL, *OBJ is assumed.

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.

End journal options

INPUT; CHAR(*)

The end journal options, if any, to use for the selection of objects to end journaling changes. If this parameter is not specified, objects will have journaling ended 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 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 is returned.

Key. Specific action for end 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 is 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 End Journal (ENDJRN) command. The following table also can be used to locate the key names that correspond to the ENDJRN command parameters.

Field Descriptions

Directory subtree. Whether the directory subtrees are included in the end journal operation. If this parameter is not specified, the default is *NONE.

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 processing. 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 field must be set to 32.

Include or omit. Whether the name pattern is included or omitted from the 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.

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 ends journaling a directory object and all objects within that directory subtree. Additionally, it ends 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";

    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 name, 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));

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

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

    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;

    QjoEndJournal(&objectEntryArray,
                  &fileIDEntryArray,
                  (Qlg_Path_Name_T *)NULL,
                  (Qjo_Journal_Options_t *)&journalOptions,
                  &errorCode);
}