| 1 | Object entry | Input | Char(*) |
| 2 | File ID entry | Input | Char(*) |
| 3 | Journal | Input | Char(*) |
| 4 | End journal options | Input | Char(*) |
| 5 | Error code | I/O | Char(*) |
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 CL commands:
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.
| 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 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.
| 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.
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.
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.
| 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.
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.
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.
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.
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.
| Key | Input Type | Field | Length of Option Record |
Length of Data |
ENDJRN Command Parameter |
|---|---|---|---|---|---|
| 1 | CHAR(5) | Directory Subtree | 32 | 5 | SUBTREE |
| 2 | CHAR(48) | Name Pattern | 64 | 48 | PATTERN |
| 3 | CHAR(1) | Logging Level | 32 | 1 | LOGLVL |
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.
| *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. |
Include or omit. Whether the name pattern is included or omitted from the operation.
| *INCLUDE | Objects that match the object name
pattern are processed, unless overridden by an *OMIT specification. |
| *OMIT | Objects that match the object name pattern are not processed. This overrides an *INCLUDE specification and is intended to be used to omit a subset of a previously selected pattern. |
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.
Logging level. Specifies the error logging level used. This key is used to determine which messages will be sent. If this key is not specified, the default is 2.
| 1 |
*ALL - The API sends all the messages that would be sent with *ERRORS and
it will also send the successful completion message for each object. |
| 2 | *ERRORS - All diagnostic and escape messages are sent but the API will not send successful completion messages for each object. At the completion of this API, one completion message will be sent. |
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 topic collection.
Note: This parameter is ignored if the object entry parameter is not specified.
| 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.
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.
Reserved. A reserved field that must be set to hexadecimal zeros.
The following messages may be sent from this API:
| Message ID | Error Message Text |
|---|---|
| CPFA0D4 E | File system error occurred. |
| CPF0B3F E | The reserved area is not set to binary zeros. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C88 E | Number of variable length records &1 is not valid. |
| CPF694A E | Number in array value &1 for key &2 not valid. |
| CPF694B E | Length &1 of variable record for key &2 not valid. |
| CPF694C E | Variable length record data for key &1 not valid. |
| CPF700B E | &1 of &2 objects ended journaling. |
| 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. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
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.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#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);
}
[ Back to top | Journal and Commit APIs | APIs by category ]