10
| 1 | Qualified journal name | Input | Char(20) |
| 2 | Journal entry information | Input | Char(*) |
| 3 | Entry data | Input | Char(*) |
| 4 | Length of entry data | Input | Binary(4) |
| 5 | Error Code | I/O | Char(*) |
| 6 | Receiver variable | Output | Char(*) |
| 7 | Length of receiver variable | Input | Binary(4) |
| 8 | Format of receiver variable | Input | Char(8) |
| 9 | Minimum length of entry data returned | Input | Binary(4) |
The Send Journal Entry (QJOSJRNE) API writes a single journal entry to a specific journal. The format of the entry is determined by the API caller. You can assign an entry type to the journal entry. You can associate the journal entry with additional information such as a journaled object or a commit cycle identifier.
If the journal currently has a state of *STANDBY, then the journal entry will not be deposited unless 1 is specified for the override standby key.
Note:The journal code for the entry is 'U', indicating a user-specified journal entry. See the Journal management topic for more information.
If a database file object is specified, it currently must either be journaled to the specified journal or it must have been last journaled to the specified journal.
*EXECUTE, *OBJOPR, *R, *X, *SHRUPD, *SHRRD, and O_RDONLY | O_SHARE_RDWR are required only if an object is specified in the qualified file name, qualified object name, object path, or object file identifier key fields.
The name of the journal to which the entry is to be added and the library in which it is located. The first 10 characters contain the journal name and the second 10 characters contain the library name. The special values supported for the library name are:
| *LIBL | Library list |
| *CURLIB | Current library |
Information pertinent to the journal entry that is to be added. The information must be in the following format:
The user-specified data that is placed in the variable portion of the journal entry (also known as entry specific data).
The length of the entry data parameter. Valid values are 0 - 15761440. If 0 is specified, this is equivalent to *BLANKS on the SNDJRNE CL command. If the length of the entry data is greater than 32766, then a pointer to the entry data will be returned when retrieving the entry. If the retrieve interface is expecting pointers, the data can be accessed through the pointer returned on the retrieve. Otherwise, the data returned by the retrieve interface will be *POINTER.
The structure in which to return error information. For the format of the structure, see Error code parameter.
The receiver variable that receives the entry information for the journal entry just deposited. You can specify the size of the area smaller than the format requested as long as you specify the length of receiver variable parameter correctly. As a result, the API returns only the data the receiver variable can hold. This parameter is ignored if Length of receiver variable is 0.
The length of the receiver variable specified in the user program. If the length of the receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The allowed values are 0 or a value of 8 or greater. The default value is 0.
The following formats are valid inputs: SJNE0000 and SJNE0100. The default value is SJNE0000, which indicates that the Receiver variable parameter is not being used. See the SJNE0100 Format for more information.
The minimum number of bytes of entry data the caller wants returned on interfaces that retrieve journal information when the length of the entry data is greater than 32766. A pointer will be returned to the remaining information. The default value for this parameter is 0, which indicates that only the pointer will be returned as entry specific data.
If the length of entry data is 32766 or less, the value of the Minimum length of entry data returned parameter must be 0. If the length of entry data is greater than 32766, the user may specify a value of 0 or a multiple of 16 (up to a maximum of 32736) indicating how much of the entry data parameter should be returned as entry specific data prior to a pointer addressing the rest of the entry specific data.
Example: The length of entry data is 40,000 so a pointer to the data will be returned when the journal entry is retrieved. The caller, however, wants the first 16 bytes of the entry data to be returned prior to the pointer and for the pointer to address the remaining 39,984 bytes. This can be done by specifying a Minimum length of entry data returned parameter value of 16. The 16 bytes of user data that are returned as entry specific data could contain information such as the length of data addressed by the pointer.
When the length of entry data is greater than 32766, all of the actual data cannot be returned on interfaces that retrieve journal entry information. Instead, on these interfaces, a pointer is returned to the actual data.
Note: The user of the QJOSJRNE API must pass all or none of the parameters in Optional Parameter Group 1.
The following table defines the format for the variable length records.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Key |
| 4 | 4 | BINARY(4) | Length of data |
| 8 | 8 | CHAR(*) | Data |
If the length of the data is longer than the key field's data length, the data will be truncated at the right. No message will be issued.
If the length of the data is smaller than the key field's data length, an error message (CPF3C4D) will be issued.
It is not an error to specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.
Each variable length record must be 4-byte aligned. If not, unpredictable results may occur.
Data. The data used to determine how the journal entry should be sent. All values are validity checked.
Key. Identifies specific information about the journal entry that will be sent. See Keys for the list of valid keys.
Length of data. The length of the journal entry information value. The length of data field is used to get the addressability of the next attribute record.
The following table lists the valid keys for the key field area of the variable length record.
Some messages for this API refer to parameters and values of the Send Journal Entry (SNDJRNE) command. This table also can be used to locate the key names that correspond to the SNDJRNE command parameters.
| Key | Type | Field | SNDJRNE Command Parameter |
|---|---|---|---|
| 1 | CHAR(2) | Journal entry type | TYPE |
| 2 | CHAR(20) | Qualified file name | FILE |
| 3 | CHAR(10) | Member name | FILE |
| 4 | CHAR(1) | Force journal entry | FORCE |
| 5 | CHAR(1) | Include commit cycle identifier | Not applicable |
| 6 | CHAR(40) | Qualified object name | OBJ |
| 7 | CHAR(*) | Object path name | OBJPATH |
| 8 | CHAR(16) | Object file identifier | OBJFID |
| 9 | CHAR(1) | Override journal state | OVRSTATE |
|
10 |
CHAR(1) | Override remote filter | OVRRMTFTR
|
Force journal entry. Whether the journal receiver is forced to auxiliary storage after the user entry is written to it. Possible values are:
| 0 | The journal receiver is not forced to auxiliary storage. This is the default value if the key is not specified. |
| 1 | The journal receiver is forced to auxiliary storage. |
Include commit cycle identifier. Whether the commit cycle identifier should be included with this user journal entry when it is written. The commit cycle identifier will be the one associated with the commitment definition that is being used by the program that calls this API. Possible values are:
| 0 | The commit cycle identifier is not included and will not be written with this user journal entry. This is the default value if the key is not specified. |
| 1 | The commit cycle identifier is determined and
will be associated with this user journal entry if it is available. So that the
commit cycle identifier can be determined for the specified journal, you
must have registered an API commitment resource with the Add
Commitment Resource (QTNADDCR) API. Also, you must have specified that this
journal was associated with this commitment resource. For more information, see
Add Commitment Resource (QTNADDCR) API.
Note: If commitment control is not active for the program that calls this API, an error will be returned as no commit cycle identifier is available. You can use the Retrieve Commitment Information (QTNRCMTI) API to determine whether commitment control is active or not for the commitment definition of the program that calls this API. |
Notes:
Journal entry type. The journal entry type of this journal entry. Specify a 2-character value for the journal entry type. This value must be greater than or equal to hex C000. A default value of '00' (hex F0F0) is assumed if the key is not specified.
If a hexadecimal value is specified that does not represent characters, that value is not shown on the DSPJRN display or printout.
Member name. The name of the physical file member with which this entry is associated. Special values are *FIRST and *NONE. The default value is *FIRST. If file name is *NONE and this field has a specific member listed, an error will be returned. If specified file is a logical file, this field must be *NONE.
Object file identifier. The file identifier (FID) of the object with which this entry is associated. An FID is a unique identifier associated with integrated file system-related objects. Only objects of type *STMF, *DIR, or *SYMLNK that are in the "root" (/), QOpenSys, and user-defined file systems are supported.
The only special value supported is 16 bytes of hexadecimal zeros ('00000000000000000000000000000000'X) and represents no object identified by an FID will be associated with the entry. This is the default if the object file identifier key is not specified.
Object path name. The path name of the object with which this entry is associated. Only objects of type *STMF, *DIR, or *SYMLNK that are in the "root" (/), QOpenSys, and user-defined file systems are supported. Symbolic links within the path name will not be followed.
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.
The only special value supported is *NONE, and this is the default if the object path name key is not specified. If *NONE is specified, then in the path name header structure, the length must be set to 5 and *NONE must follow the path name header structure.
The maximum length of data for this key is 16,773,120.
Override journal state. Whether the journal entry will be deposited, overriding the current state of the journal. Possible values are:
| 0 | None of the journal state values are overridden.
That is,
|
| 1 | The journal entry is deposited even if the journal state is *STANDBY. |
Override remote filter. Specifies whether the journal
entry will be sent to remote journals, overriding filtering criteria.
| 0 | None of the remote journal filtering values are overridden. |
| 1 | The journal entry will be sent to remote journals even if the object specified for Key 2 (Qualified file name), Key 6 (Qualified object name), Key 7 (Object path name), or Key 8 (Object file identifier) is marked for remote journal object filtering and a remote journal is filtering journal entries by object. |
Qualified file name. The first 10 characters contain the name of the database file with which this entry is associated. The only special value supported for the file name is *NONE. The second 10 characters contain the name of the library containing the file. Special values are:
| *LIBL | Library list |
| *CURLIB | Current library |
If the file name is *NONE, then the library name is ignored. *NONE is the default if the qualified file name key is not specified.
Qualified object name. The qualified name of the object with which this entry is associated. For the format of this field, see Qualified Object Name Format.
If *NONE is specified for object name, the remaining fields should be set to blanks. *NONE is the default if the qualified file name key is not specified.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| CHAR(10) | Object name | ||
| CHAR(10) | Object library name | ||
| CHAR(10) | Object type | ||
| CHAR(10) | Member name, if *FILE specified | ||
Member name. The name of the physical file member with which this entry is associated. If the specified file is a logical file, this field must be *NONE. The possible values are:
| *FIRST | The entry is associated with the first member in the physical file. |
| *NONE | The entry is associated with the file, not with any member of the file. |
| member name | The name of the physical file member with which this entry is associated. |
| blank | The member name field must be blank if *NONE is specified for the object name. |
Note: If the specified object type was not *FILE, the member name value is ignored.
Object library name. The name of the library containing the object. The possible values are:
| *LIBL | All libraries in the job's library list are searched until the first match is found. |
| *CURLIB | The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used. |
| library name | The name of the library to be searched. |
| blank | The library name field must be blank if *NONE is specified for the object name. |
Object name. The name of the object with which this entry is associated.
| *NONE | No object is associated with the journal entry. |
| Object name | The name of the object with which this entry is associated. |
Object type. The object type associated with the object with which this entry is associated. The possible values are:
| *FILE | The entry is associated with a database file or database physical file member. |
| *DTAARA | The entry is associated with a data area. |
| *DTAQ | The entry is associated with a data queue. |
| *LIB | The entry is associated with a library. |
| blank | The object type field must be blank if *NONE is specified for the object name. |
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(20) | Sequence number |
| 28 | 1C | CHAR(10) | Journal receiver name |
| 38 | 26 | CHAR(10) | Journal receiver library |
| 48 | 30 | CHAR(10) | Journal receiver ASP device name |
Bytes available: The length, in bytes, of the SJNE0100 information available for the API to return to the caller.
Bytes returned: The number of bytes that are being returned in the receiver variable.
Journal receiver ASP device name: The name of the ASP device on which the journal receiver resides.
Journal receiver library: The name of the library that contains the journal receiver.
Journal receiver name: The name of the journal receiver that contains the sent entry.
Sequence number: This is the number assigned by the system to the journal entry that was just sent. This is a Char(20) field and it is treated as Zoned(20,0).
| Message ID | Error Message Text |
|---|---|
| CPFA0D4 E | File system error occurred. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3C81 E | Value for key &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C85 E | Value for key &1 not allowed with value for key &2. |
| CPF3C88 E | Number of variable length records &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF6948 E | Length of the receiver variable &1 not valid. |
| CPF694E E | Value specified for parameter Minimum length of entry data returned not valid. |
| CPF70C3 E |
File &1 in library &2 not a database file.
|
| CPF7003 E | Entry not journaled to journal &1. Reason code &3. |
| CPF7007 E | Cannot allocate member &3 file &1 in &2. |
| CPF7037 E | File &1 not journaled to journal &3. |
| CPF706E E | Length of entry data &1 not valid. |
| CPF708D E | Journal receiver found logically damaged. |
| CPF8100 E | All CPF81xx messages could be returned. xx is from 01 to FF. |
| CPF83DE E | No API commitment resource associated with journal &2. |
| CPF83D1 E | Commit cycle identifier not available. |
| CPF8350 E | Commitment definition not found. |
| 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. |
| CPF9809 E | Library &1 cannot be accessed. |
| CPF9810 E | Library &1 not found. |
| CPF9812 E | File &1 in library &2 not found. |
| CPF9815 E | Member &5 file &2 in library &3 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9822 E | Not authorized to file &1 in library &2. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
[ Back to top | Journal and Commit APIs | APIs by category ]