Under certain conditions, not all of the journal entry data will
be immediately retrievable from a journal entry. Instead, part of the journal
entry information will include pointers to additional journal entry-specific
data.
These pointers will only be retrieved if you use following:
- Retrieve Journal Entries (QjoRetrieveJournalEntries) API
- The *TYPEPTR format on the Receive Journal Entry (RCVJRNE) command
- The *JRNENTFMT format on the RCVJRNE command (you must
also specify the RTNPTR parameter for the RCVJRNE command)
In all other retrievals of journal entry data, *POINTER would be in the
field where a pointer could exist. An incomplete data indicator has been added
to indicate if the journal entry-specific data has data missing which can
only be retrieved through a pointer
If the QjoRetrieveJournalEntries API or the *TYPEPTR
or *JRNENTFMT format on RCVJRNE command is used and the
incomplete data indicator field is 1, the journal entry-specific data will
contain pointers. For all other interfaces, if the incomplete data indicator
is 1, the journal entry-specific data will have the character string *POINTER
in the field where an actual pointer would be placed if the API or *TYPEPTR
or *JRNENTFMT interfaces were used. The incomplete data indicator field could
be set to 1 if the journal entry-specific data exceeds 32766 bytes, or if
the journal entry is associated with a database file which has one or more
fields of data type BLOB (binary large object), CLOB (character large object),
or DBCLOB (double-byte character large object). Use the Journal entry information
finder to find which journal entry types can set the incomplete data indicator
on.
These pointers can only be used with the V4R4M0 and later versions of the
following languages:
There are some considerations you need to be aware of when using the pointer
data:
- The pointer can only be used by the process or job which retrieved or
received the journal entry which contained the pointer. The pointer cannot
be passed on to another job, nor can it be stored to use at a later date by
a different job or process.
- The pointer will only give you read access to the additional data. Write
operations to that pointer are not allowed.
- The data that is being pointed to actually resides in the journal receiver.
Therefore, ensure that you protect the journal receiver from deletion until
you use the data. To prevent a journal receiver from being deleted before
the data is used, you can register an exit point for the Delete Journal
Receiver (DLTJRNRCV) command.
- For files with fields of data type BLOB (binary large object), CLOB (character),
or DBCLOB (double-byte character large object), use SQL to update the files.
If any journal entries are returned with pointers, the journal entry will
also contain a pointer handle. This pointer handle must be used to free up
any allocations associated with the pointer data once the pointer data has
been used. The considerations for this pointer handle are as follows:
- Using the pointer data means any of the following:
- Addressing the information and copying the addressed data to another object
- Using the journal entry-specific data directly to modify another object.
For example, using the data to update a database file with the journal entry
which represents a database record update for a file which included LOBs.
- Ignoring the additional data that is pointed to
- If you used the QjoRetrieveJournalEntries API, use
the Delete Pointer Handle (QjoDeletePointerHandle) API
to delete the pointer handle when you are done using it.
- If you use the RCVJRNE command with the RTNPTR(*SYSMNG)
parameter, you must use the associated pointer prior to returning control
from the exit program. The system will delete all pointer handles after the
return from the exit program call.
- If you use the RCVJRNE command with the RTNPTR(*USRMNG)
parameter, then it is your responsibility to use the Delete Pointer
Handle (QjoDeletePointerHandle) API to delete the pointer handle
when you are done using it.