Working with pointers in journal entries

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:

  • ILE/COBOL
  • ILE/RPG
  • ILE/C if the TERASPACE parameter is used when compiling the program.

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.