1 | Object entry array | Input | Char(*) |
2 | File ID entry array | Input | Char(*) |
3 | Journal | Input | Char(*) |
4 | Start journal options | Input | Char(*) |
5 | Error code | I/O | Char(*) |
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), Stream Files (*STMF), Directories (*DIR), and Symbolic Links (*SYMLNK). For objects of type *STMF, *DIR, or *SYMLNK, only objects in the "root" (/), QOpenSys, and permanent user-defined file systems are supported. For more information about the possible journal entries that can be sent, see the Journal management topic collection.
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 CL commands:
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.
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 topic collection.
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.
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.
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.
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.
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:
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.
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 Start Journal (STRJRN) command. This table also can be used to locate the key names that correspond to the STRJRN command parameters.
Key | Input Type | Field | Length of Option Record |
Length of Data |
STRJRN Command Parameter |
---|---|---|---|---|---|
1 | CHAR(5) | Directory subtree | 32 | 5 | SUBTREE |
2 | CHAR(*) | Name pattern | * | * | 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 |
6 | CHAR(1) | Logging Level | 32 | 1 | LOGLVL |
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. |
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. |
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 the start journal operation. The default will be to include all patterns that match. For the format of this field, see Name Pattern Format.
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.
Note: This parameter only applies to objects that exist when the API is called. This parameter does not apply to objects that will be created later in a journaled directory where new objects inherit journaling.
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. |
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. |
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 |
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. |
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.
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. |
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. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
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.
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"; 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); }
[ Back to top | Journal and Commit APIs | APIs by category ]