I have finally managed to get the QDBRPLAY API up and running alongside the APYJRNCHG command. The reason I needed the API was because of a customers need to have RAP configure a single journal environment which would support the automatic creation of files as well as the IFS Files. I had hoped to also bring automatic creation of Data Area’s and Data Queues into the same PTF for Version 1.1 but unfortunately that wont work. I will explain more on that later.
I did say I would publish the code for the API but I dont have the time at the moment to publish a full solution so I will just publish a few snippets which explain how the API is configured. One problem we did come across was which Entries we needed to replay through the API to allow the files to be created correctly. You need to ensure you retrieve both the DCT and FMC entries for the solution to work. We intermingled the retrieval of the journal entries with the APYJRNCHG command to ensure we followed the correct sequence that was produced through the use of the APYJRNCHGX command.
Basic code path is as follows
- Retrieve the journal entries
- Apply entries up to the first entry retrieved
- Apply the first retrieved entry using the QDBRPLAY API
- Check if any entries between applied entry and the next retrieved
- If any entries apply them, then apply the next retrieved entry
- do loop until last retrieved entry applied
- Apply any entries past last retrieved to the end
The API’s we used are
- QoRetrieveJournalInformation to get the sequence number information
- QjoRetrieveJournalEntries to get the journal entries we are interested in
- QjoDeletePointerHandle to remove the handle associated with the retrieved journal entry
- QUSCRTUS to create a user space to hold the Entry Specific Data from Teraspace and Journal entry
- QUSPTRUS to get a pointer to the User space
- QUSDLTUS to delete the User spaces after we had finished with them
- QDBRPLAY to apply the journal entries DCT and FMC
Structures we used from the C header files.
- Qjo_RJNE0200_Hdr_t for the header of the User Space to get to the returned entries
- Qjo_RJNE0200_JE_Hdr_t addresses the header for each entry returned
- Qjo_RJNE0100_JE_ESD_t to address the Entry Specific Data for each entry returned
- Qjo_RRCV0100_t for addressing the Receiver information
- Qdb_Rename_Exit_Parm_t for the rename scratch pad passed to the QDBRPLAY API.
We created the following structures
- DBR_Tmp_Str_t This is the input template
- ESD_Tmp_Str_t This is for addressing the Entry Specific Data
Things which we found out as part of the build and which are important to understand.
The Input Template Qdb_DBRR0100_t structure in the header file is incomplete. We created the DBR_Tmp_Str_t structure with a char[2] array at the end.
The ESD Template QdbJrnl_DDL0100_t is incomplete, we created the ESD_Tmp_Str_t structure with a character pointer at the end.
You have to set the char[2] array to 0x00 before passing it into the API. We used the memset function to achieve this using memset(Input_Template.Reserved,0x00,sizeof(Input_Template.Reserved);.
The values in the Input Template were set using normal C functions such as memcpy etc. Here are the settings we used. Input_Template is the structure DBR_Tmp_Str_t and here are the elements in the Qdb_DBRR0100_t structure.
Rename_Exit_Pgm *NONE.
Disable_Trigger = ‘0’.
Journal_Type is copied from the journal entry retrieved.
Journal_Code is copied from the journal entry retrieved.
The Input_Template_Len is set using sizeof(Input_Template).
The biggest challenge was how to pass in the ESD especially if the data was stored in teraspace. The ESD data returned will have a 16byte address pointer for the last 16 bytes returned if a teraspace pointer is used. Also the flag Incomplete_Data in the Journal Entry Header will be set. Another thing to consider is the Pointer_Handle which is set, this has to be released after you have finished with the entry otherwise you could end up using all the handles from the system! Ending the process also releases the handles, but this process may not end for a long time if at all?
To get to the teraspace data and move it to a single place before we pass it into the QDBRPLAY API we used a UserSpace object to hold all the information. Remember the last 16 bytes of the data returned in the ESD structure is an address and has to be removed before adding the teraspace data. Simple put, get the length of the ESD Data copy the length minus the 16 bytes to the UserSpace, then copy the teraspace data to the end of that data! The manuals are very confusing on how to achieve this so take care. The API is called as a service program so even if it has a problem your program can continue, it just burps and carries on! Simple solution for us was to only create the Userspace if the flag was set for extra data, otherwise we set a character pointer to the returned journal entry and passed that in. (Sorry if thats confusing I cant think how better to explain it this late at night!)
Here is the API call.
QDBRPLAY(&Input_Template,
&Input_Template_Len,
Input_Template_Fmt_Name,
esddta,
&ESD_Len,
&Scratch_Pad,
&Error_Code);
Thats about it! It all worked in the end and the process work well with the APYJRNCHG commands so it will be released as a PTF in the RAP product by the end of the month. If I get a bit more time I will try to publish a bit more of the code if people ask for it..
Chris….