APYRMTJRN -- Apply Remote Journal

APYRMTJRN APPLY REMOTE JOURNAL TAAJROD
The Apply Remote Journal tool provides 'real time' data replication to a remote system using the system remote journaling support. Only data from data base file members, data areas, and data queues are supported. The function may be used for a variety of application needs. If used for high availability, you have the responsibility of keeping the environment in synch (such as changes to programs, object attributes, etc). **************************************** * * * If you are considering the use * * of this tool, check with the * * TAA Productivity Tools owner. * * You will be kept on the list * * for significant changes and * * fixes for APYRMTJRN. * * * ************************************** The system remote journaling support allows a journal receiver on a local system to be replicated to a journal receiver on a remote system. The system APYJRNCHG command cannot be used to apply the entries because the apply may only be done to the original file. (The system assigns a unique journal ID (JID) for each file that is journaled which includes an identification of the originating system. If the JID does not match between the file and the journal entries, APYJRNCHG cannot be used). The TAA Start Apply Remote (STRAPYRMT) command runs on the remote system as an application program to apply the entries. STRAPYRMT uses batch jobs to extract the journal entries and applies them to corresponding objects on the remote system. The same library/object names must be used on the remote system. Because the APYRMTJRN tool only handles the data portion of objects, it is only effective for high availability if you have a fairly static environment. This means that programs, display files, data base file attributes, authorizations, etc do not change frequently and you have good control over the changes. The APYRMTJRN tool does not replicate changes such as CHGPF, GRTOBJAUT, etc. You must replicate these changes yourself on the remote system. You can use APYRMTJRN to just replicate the data to a remote system if you are only interested in real time backup of the data. The APYRMTJRN tool supplies its own subsystem and job queue. This provides a convenient method of starting and ending the function. Major requirements ------------------ Prepare for remote journaling. Consider what objects and libraries will be used. Journal the objects that you want to replicate the data for. See the section on 'Preparing APYRMTJRN'. Synchronize the objects between the local and remote systems. This normally means that you end the application on the local system, do a save of the objects, and restore them to the remote system. See the section on 'Preparing for APYRMTJRN'. Set up remote journaling on the local/remote systems. See the section on 'Setting up remote journaling'. Enter the STRAPYRMT command on the remote system to begin the function. This causes the APYRMTJRN subsystem to be started and the APYRMTJRN jobs to be submitted. Monitor the results. This includes reviewing an error message queue and spooled output from APYRMTJRN. Keep the environments in synch. This means you must replicate program changes, authorizations, etc. See the section on 'Keeping the environment in synch'. Considerations -------------- Data base files up to 32,000 bytes in record length are supported including null values and variable length fields. The system supports a maximum length of 32,766. Because of the 32K restriction, it is unlikely that BLOB and CLOB data types could be used. Data queue entries up to 32,000 bytes (as the maximum length defined for the data queue) are supported. The system supports a maximum length of 64,512. Both keyed and non-keyed data queues are supported as well as 'sender ID'. Data areas of any size or type are supported. Stream files (from the IFS) are not supported. The CRTJRN MINENTDTA(YES) for 'minimize entry specific data' is supported. * Up to 32,767 different objects (type/library/object/member) can be processed from a single journal. The object and library names to be replicated must be the same on the local and remote system. Special journal entries for commitment control are not considered. The journal entries are processed as they appear. No attempt is made to buffer the entries and apply them only if a commitment boundary is reached. If a rollback occurs, journal entries will exist and will be processed to roll the data back. See the later discussion of 'Commitment Control processing'. For Referential Integrity and Trigger handling see the section on 'Referential Integrity and Triggers'. The minimum release is V5R1, but the local and remote system may be on different releases. ** The number of entries to be processed is only limited by your systems capability to apply them. See the section on 'Preparing for APYRMTJRN' for assistance in checking for the limits imposed by the tool and other help. Demonstrating the APYRMTJRN function on a single system ------------------------------------------------------- You can take the APYRMTJRN tool for a 20 minute 'test drive' on a single system by using some supplied test programs. The remote system is simulated by using a different library on the local system. A second demonstration exists (described later) that uses both a local and remote system. The second demonstration requires additional setup to use. It is highly recommended that you use these demonstrations to gain an overall understanding of remote journaling and how the APYRMTJRN tool operates. Using the single system demonstration is the simplest version and should assist you in understanding the documentation and detail functions. To see the full text of messages, you may prefer to operate from the full command entry display. CALL PGM(QCMD) Do the following steps all on the 'local' system. 1. Ensure the TAATOOL library is on your library list by entering: EDTLIBL If the TAATOOL library does not exist, add it: 2. Ensure the libraries APYRMTJRN, TAATSTLCL, and TAATSTSIM do not exist. DSPLIB LIB(APYRMTJRN) DSPLIB LIB(TAATSTLCL) DSPLIB LIB(TAATSTSIM) If any of the libraries exist from a prior use of a demonstration and you want to start over, enter: CALL PGM(TAAJRODC49) 3. To set up the environment, enter the command: CALL PGM(TAAJRODC41) The TAAJRODC41 program will create the 3 libraries and various objects. -- The TAATSTLCL library contains the objects on the local system that will be replicated to the simulated remote system. Since these objects must be journaled, a journal and journal receiver are also placed in the library (they could be in a different library). Display the 'local' library with: DSPLIB LIB(TAATSTLCL) The journal and journal receiver are used to simulate remote journaling. RCV0001 JRNRCV JRN1 JRN You should also see the following objects which will be replicated: DTQKEYED DTAQ Keyed (no entries) DTQNONKEY DTAQ Non-keyed (no entries) DTQ2 DTAQ Second non-keyed (no entries) DSPOBJDP FILE Created by DSPOBJDP OUTFILE No data exists FILEA FILE Small amount of data FILEB FILE Small amount of data DTAARAC DTAARA Character type DTAARAD DTAARA Decimal type The variety of object types provides a good sample of the replication capability of the APYRMTJRN tool. When CRTJRN is used, the default for MNGRCV is SYSTEM meaning the system will manage the change of receivers. In some cases the system will reset the sequence numbers which will prevent the APYRMTJRN from operating properly. Therefore, any journals that are to be used should be specified as USER managed. While this is not critical for the demonstration, you should get in the habit of specifying MNGRCV(USER). CHGJRN JRN(TAATSTLCL/JRN1) MNGRCV(USER) -- The TAATSTSIM library contains the objects that are simulated to be on the remote system. Display the simulated 'remote' library with: DSPLIB LIB(TAATSTSIM) The data base, data area, and data queue objects in the TAATSTLCL and TAATSTSIM libraries are identical. The objects exist as if you synchronized them using a save and restore. -- The APYRMTJRN library contains the controlling objects created by the Create Apply Remote Description (CRTAPYRMTD) command. The library would exist on the remote system in an actual use of the tool, but for the test function, the library will be on the local system. Display the APYRMTJRN library: DSPLIB LIB(APYRMTJRN) The APYRMTJRN library includes a unique subsystem and job queue to simplify starting and ending the APYRMTJRN function. Data base and user space (USRSPC) objects also exist which contain control information and will be used for communication between the apply jobs. The message queue TSTMSGQ exists which is set to BREAK mode for the demonstration. A message queue is required by APYRMTJRN (QSYSOPR is the default) to provide for a quick indication of any problems that may arise. The message queue can be in any library. 4. To start the APYRMTJRN function and cause changes to the objects being journaled, enter the command: CALL PGM(TAAJRODC42) This causes the STRAPYRMT command to be run which starts the APYRMTJRN subsystem. Two batch jobs are automatically started. Changes are made to the objects being journaled. 5. Use WRKSBS to display the active subsystems: WRKSBS Use Option 8 to display the jobs for the APYRMTJRN subsystem. You should see the batch jobs APYRMTJRN, APYRMTJRN1, and APYRMTJRNC. The APYRMTJRN job extracts the entries from the simulated journal receiver. The APYRMTJRN1 job applies the entries. There can only be one APYRMTJRN job per remote journal, but you can have up to 9 jobs which apply the entries. APYRMTJRNC is a special job that wakes up every 10 minutes and checks if the other batch jobs are still active. If not, it sends a message to the message queue specified on CRT/CHGAPYRMTD if it is in BREAK mode. If the message queue is not in BREAK mode, the same message is sent to QSYSMSG if it exists and QSYSOPR if it does not. Use F3 to exit the WRKSBS display. 6. All of the objects intended for replication from TAATSTLCL were changed by the TAAJRODC42 program which caused journal entries to be made. The tool has already applied these entries to the corresponding objects in TAATSTSIM. The following processing has occurred: The DTAARA objects have changed in value. The DTAQ types have had entries sent and received from them. The data base files have been changed - A DSPOBJD OUTFILE function has added records to DSPOBJDP - FILEA has had an update, a delete, and an add - FILEB has had an update, a delete, and an add using commitment control and then the same functions were rolled back by a de-commit (RPG ROLBK operation) 7. Compare the objects and their data by entering: CALL PGM(TAAJRODC43) Error messages will be sent if any of the objects do not match. 8. A spooled file has been generated for each of the data queues and data base files that were compared. You can review these with WRKSPLF, but if the entries compared properly, there is not much benefit. 9. To review the entries that exist in the journal, enter: DSPJRN JRN(TAATSTLCL/JRN1) APYRMTJRN retrieves every journal entry, but only processes some of the entry types and codes. See the section on 'Journal Codes/Types that are processed'. 10. To end the APYRMTJRN function, enter the command: ENDAPYRMT You should see a break message that describes that APYRMTJRN is ending. Both the APYRMTJRN master job, the APYRMTJRN1 apply job, and the APYRMTJRNC job will end after a few seconds. The default of FRCJOBLOG(NO) was taken on CRTAPYRMTD so no job logs should exist. 11. Verify that the subsystem is no longer active using: WRKSBS 12. Review the spooled files created by each job. WRKSPLF The APYRMTJRN spooled file (may appear after the APYRMTJRN1 spooled file) is standard and reflects the processing of the APYRMTJRN job. The APYRMTJRN1 spooled file is optional and reflects the processing of the APYRMTJRN1 job. 13. When APYRMTJRN completes, a data base file is written out with the objects that were being journaled. Note that you do not have to describe what is be replicated with APYRMTJRN. It assumes that every journal entry that causes a data change has a corresponding object to be updated. To see the file that was written, enter the Work Apply Remote (WRKAPYRMT) command: WRKAPYRMT This will describe the objects that are now known to the tool. -- Option 5 lets you review the detail information. -- Option 2 lets you change the default options: You can specify which batch apply job (1 - 9) should be used the next time you use the APYRMTJRN function. The default is 1 for the APYRMTJRN1 apply job. Using multiple batch jobs should only be done if you are not getting enough throughput from the default apply job. You can specify how to 'recover' the object if a simple error occurs (such as attempting to update a Relative Record number which does not exist). The default is S/R meaning that you will resynch the object by doing a Save and Restore or by use of the Send Apply Remote Entry (SNDAPYRMTE) command using OPTION(CPY). You may specify EDT which means you will resynch the object by changing it on the remote system such as by using the TAA Edit Data Base File (EDTDBF) command to change individual data base records. This may be a better technique to choose if there are many data base records in a file and the Save/Restore process would be too long to be practical. See the later discussion of 'Re-synching an object'. While the major use of the EDT option is intended for data base files, it may also be used for data areas or data queues. Note that on the WRKAPYRMT main display, the F11 key may be used to alternate between a display of which batch apply program to use and the recovery type. -- Option 4 will let you delete the record describing the object. The intent of the function is to allow cleanup if an object no longer exists. If you accidentally delete an object that is still being used, no error will occur. The tool will add an entry for the object if any journaling activity takes place. WRKAPYRMT can be entered at anytime, but any change in definition will not be used until the next time STRAPYRMT is used or a refresh occurs. 14. To review the APYRMTJRN description, enter the Display Apply Remote Description (DSPAPYRMTD) command: DSPAPYRMTD This describes the control information in the APYRMTJRND user space in library APYRMTJRN. Most of the information was specified on the CRTAPYRMTD command (run for you in TAAJRODC41). Note that one of the attributes describes the last journal entry sequence number that was processed. This allows the function to restart properly when used again. The journal receiver of the first journal entry when STRAPYRMT was used is displayed. This is updated when ENDAPYRMT is used. Most of the values in the APYRMTJRND user space can be changed by the Change Apply Remote Description (CHGAPYRMTD) command which prompts with the current values. Enter the command and press Enter. CHGAPYRMTD Note that changing some values such as the journal name should only be done if you have significantly changed the environment. 15. The APYRMTJRN subsystem was ended in a previous step and is no longer active. If you want to restart the function for further testing, enter (F9 must be used with command prompting to access the TSTLIB parameter): STRAPYRMT APYRMTLIB(APYRMTJRN) TSTLIB(TAATSTSIM) The TSTLIB parameter describes that you will be updating entries into a test library on the local system and not the same library name on a remote system. You may now try any additional functions such as changing some of the existing objects in TAATSTLCL and checking whether results were made to the corresponding object in TAATSTSIM. For example, you could do the following: CHGDTAARA DTAARA(TAATSTLCL/DTAARAC) VALUE('ABC') SNDDTAQ DTAQ(TAATSTLCL/DTQ2) ENTLEN(50) ENTRY('APYRMTJRN test') DSPOBJD OBJ(TAAJRODC4) OBJTYPE(PGM) OUTPUT(OUTFILE) OUTFILE(TAATSTLCL/DSPOBJDP) OUTMBR(FIRST ADD) You can add a member to FILEA (allows up 10 members) and copy from the first member to the new member. You can update a record in a FILEA member by using EDTDBF such as: EDTDBF FILE(TAATSTLCL/FILEA) MBR(xxx) You can check the results manually by using: DSPDTAARA DTAARA(TAATSTSIM/DTAARAC) DSPDTAQ DTAQ(TAATSTSIM/DTQ2) PRTDB2 FILE(TAATSTSIM/DSPOBJDP) Or you can check the results with the program: CALL PGM(TAAJRODC43) You can add your own objects to TAATSTLCL and TAATSTSIM (they must be synchronized) and then use STRJRNPF or STRJRNOBJ to start journaling to the objects in library TAATSTLCL. Specify the JRN1 journal in TAATSTLCL such as: STRJRNPF FILE(xxx) JRN(TAATSTLCL/JRN1) STRJRNOBJ OBJ(yyy) OBJTYPE(zzz) JRN(TAATSTLCL/JRN1) Then make any changes you want to your objects in the TAATSTLCL library. You can review the results manually or use TAAJRODC43 again. The program will compare any data files, data areas, or data queues found in the TAATSTLCL library with the corresponding objects in TAATSTSIM. Two other test programs exist that may be used after TAAJRODC41 to allow volume testing. The first program (TAAJRODC44) allows you to create up to 999 additional files. To create 100 files specify: CALL PGM(TAAJRODC44) PARM('100') The files will be named TSTF001 - TSTF100. The second program allows you to write n records to each of the files. CALL PGM(TAAJRODC45) PARM('00200') 200 records would be written to each of the TSTFn files. You may use TAAJRODC45 at any time to add additional records to the TSTFn files. For example, you could run the program before and after ENDAPYRMT. TAAJRODC43 may be used at any time to compare the objects in the two libraries. If you are finished with the demonstration, end the function: ENDAPYRMT 16. If you have completed the demonstration and want to cleanup or repeat the demonstration from the beginning, a special program exists to delete the libraries. CALL PGM(TAAJRODC49) Demonstrating APYRMTJRN on both the local and remote systems ------------------------------------------------------------ This demonstration requires that you be signed onto both the local and remote systems. Be sure to explicitly follow the instructions about whether the command should be run on the 'local' or the 'remote' system. 1. On both systems, ensure the TAATOOL library is on your library list by entering: EDTLIBL If the TAATOOL library does not exist, add it: 2. On the 'local' system, ensure the library TAATSTRMT does not exist by entering. DSPLIB LIB(TAATSTRMT) If the library exists, it is probably left over from a previous use of the demonstration. See the section on 'Cleaning up the local and remote system demonstration' (it follows this section) to delete the demonstration objects on both the 'local' and 'remote' systems. Then return to the next step. 3. On the 'local' system, create the TAATSTRMT library and the test objects. CALL PGM(TAAJRODC81) 4. On the 'local' system, display the contents of the TAATSTRMT library. DSPLIB LIB(TAATSTRMT) You should see: RCV0001 Journal receiver JRN1 Journal DTQ1 Data queue. No entries exist. TSTFILE Data Base file. No records exist. DTAARA1 Data area. Blanks exist. To keep the test very simple, only these objects will be replicated. The journal and journal receiver objects establish the base required by the system remote journaling support. The data area, data queue, and data base file are all journaled to JRN1 in TAATSTRMT. It is important that the journal be USER managed rather than SYSTEM managed. When the system manages receivers, it changes new receivers on an IPL of either system and often resets the journal sequence numbers. Changing receivers is not a problem when using APYRMTJRN, but resetting the sequence numbers is. All journals intended for use with APYRMTJRN should be MNGRCV(USER). A later discussion describes how to reset the sequence numbers (See the section on 'Resetting journal sequence numbers'). Enter the command: CHGJRN JRN(TAATSTRMT/JRN1) MNGRCV(USER) 5. On the 'remote' system, ensure library APYRMTJRN does not exist by entering. DSPLIB LIB(APYRMTJRN) If the library exists, use DLTLIB (you may have to respond 'I' to ignore the message that the journal receiver has not been saved). 6. On the 'remote' system, create the environment, with: CALL PGM(TAAJRODC82) This creates the TAATSTRMT library (same name as on the local system) and the objects that will be replicated. 7. On the 'remote' system, display the contents of the TAATSTRMT library: DSPLIB LIB(TAATSTRMT) You should see: DTQ1 Data queue. No entries exist. TSTFILE Data Base file. No records exist. DTAARA1 Data area. No value exists. The objects are not journaled. This could be done to a journal on the remote system, but is not needed for the demonstration. 8. On the 'local' system, to check the communication environment, enter the command: WRKRDBDIRE You must have an RDB (Relational Data Base) entry established to the 'remote' system. If you are not familiar with the communication requirements, see the section on 'Setting up remote journaling communications'. 9. On the 'local' system, use the ADDRMTJRN command to add a remote journal. Use the RDB name as specified on WRKRDBDIRE. ADDRMTJRN RDB(xxx) SRCJRN(TAATSTRMT/JRN1) TGTJRN(SRCJRN) TEXT('Used by the TAA APYRMTJRN test') 10. On the 'remote' system, enter: DSPLIB LIB(TAATSTRMT) You should see that the system has created the JRN1 journal for you. 11. One of the critical requirements to make the system remote journaling function successful is to ensure that the 'journal state' of the remote journal is ACTIVE. Although you are checking the 'journal state' of the 'remote' system, the check must be performed on the 'local' system. The TAA command Check Remote Journal (CHKRMTJRN) can be used to check this. On the 'local' system, enter: CHKRMTJRN SRCJRN(TAATSTRMT/JRN1) You should see the TAA9895 escape message stating that the 'journal state' is INACTIVE. A later section will discuss 'Keeping the remote journal active'. For the demonstration, proceed to the next step. 12. On the 'local' system, to activate the journal, enter: WRKJRNA JRN(TAATSTRMT/JRN1) Use F16 (Work with remote journal information), and then Option 13 (activate). Note that the 'journal state' does not change when Option 13 is used (you must press F5 = Refresh to see the new 'journal state'). 13. On the 'remote' system, to see the change in the library, enter: DSPLIB LIB(TAATSTRMT) You should see that the system has added the RCV0001 journal receiver. The system will automatically duplicate entries from the 'local' journal to the 'remote' journal. The receiver used on the 'remote' system is like any other journal receiver. You must delete old journal receivers (after the entries have been applied) based on a retention schedule. 14. On the 'remote' system, to see the journal entries, enter: DSPJRN JRN(TAATSTRMT/JRN1) You should see the entries: PR Describes any previous journal receiver JF Starts journaling of a file JM Starts journaling of a member EG Starts journaling of a data area QB Starts journaling of a data queue These entries will be ignored by the apply program as they do not change the data in an object. If you display the journal on the 'local' system, you would see the same entries. 15. On the 'remote' system, create the library needed for the TAA APYRMTJRN function: CRTLIB LIB(APYRMTJRN) TEXT('Used by TAA APYRMTJRN tool') 16. On the 'remote' system, create a message queue and set it in BREAK mode. CRTMSGQ MSGQ(APYRMTJRN/TSTMSGQ) TEXT('Used by TAA APYRMTJRN tool') CHGMSGQ MSGQ(APYRMTJRN/TSTMSGQ) DLVRY(BREAK) Placing the message queue in break mode is important so you will be quickly informed of any errors or important events. For the demonstration, the message queue is placed in the APYRMTJRN library. This message queue will be used on the CRTAPYRMTD command instead of the default name of QSYSOPR. Any message queue and library could be used. 17. On the 'remote' system, create the objects needed for the TAA APYRMTJRN function: CRTAPYRMTD JRN(TAATSTRMT/JRN1) MSGQ(APYRMTJRN/TSTMSGQ) 18. On the 'remote' system, display the library with the controlling objects. Enter: DSPLIB LIB(APYRMTJRN) The APYRMTJRN tool has its own subsystem and job queue. User spaces (USRSPC object type) are used for communication between the APYRMTJRN jobs and to hold the definition created by CRTAPYRMTD. The data base files are used by WRKAPYRMT. For a more complete description of the objects, see the section on 'APYRMTJRN objects'. 19. On the 'remote' system, start the TAA APYRMTJRN function with the command: STRAPYRMT 20. On the 'remote' system, display the active subsystems: WRKSBS Use Option 8 to display the jobs for the APYRMTJRN subsystem. You should see the batch jobs APYRMTJRN, APYRMTJRN1, and APYRMTJRNC. See the section on 'APYRMTJRN Jobs' for a discussion of these jobs. 21. On the 'local' system, call the program to add, update, and delete records in the file TSTFILE, change the data area, and send and receive entries from the data queue. CALL PGM(TAAJRODC83) 22. On the 'local' system, review the spooled output of the data base changes in the spooled file TSTFILE: WRKSPLF The output describes that 3 records were added to the TSTFILE data base file. Then one of the records was deleted, and one was updated. 23. Be sure to wait a few seconds after any change to an object which is being replicated before displaying the corresponding object on the 'remote' system. There are 'wait' times specified in the APYRMTJRN function and the 'remote' system needs some time to wake up and apply the entries. 24. On both the 'local' and 'remote' systems compare the data base file using: PRTDB2 FILE(TAATSTRMT/TSTFILE) 25. On both the 'local' and 'remote' systems compare the data area using: DSPDTAARA DTAARA(TAATSTRMT/DTAARA1) 26. On both the 'local' and 'remote' systems compare the data queue using: DSPDTAQ DTAQ(TAATSTRMT/DTQ1) An entry can be sent to a data queue and then received. When a 'receive' occurs, the entry is removed. Each send or receive causes a journal entry. The apply program processes both the 'send' and 'receive' entries. The test program sent two data queue entries and then received the first entry. Therefore, only the second entry still exists. 27. On the 'remote' system, to review the journal entries, enter: DSPJRN JRN(TAATSTRMT/JRN1) 28. On the 'remote' system, end the APYRMTJRN function by entering: ENDAPYRMT You should see a break message that the APYRMTJRN function is ending. 29. On the 'remote' system, review the the spooled output with: WRKSPLF The APYRMTJRN spooled file describes a summary of the processing of the APYRMTJRN job. The APYRMTJRN1 spooled file is optional (see CRTAPYRMTD PRTAPYSTAT parameter) and describes the processing of the APYRMTJRN1 job. 30. The objects that were changed by journal entries are now known to the APYRMTJRN function on the 'remote' system. Each object has caused a record to be written to the APYRMTP file in APYRMTJRN. On the 'remote' system, review these records by entering: WRKAPYRMT The next time APYRMTJRN is started by STRAPYRMT, these records are used to create an internal table which is searched using a binary search technique. Any journal activity for objects that are not in the internal table are placed in an overflow area and will be 'known' when APYRMTJRN is shutdown. Using WRKAPYRMT, you can change which Batch job is used to apply the entries (up to 9 batch jobs may be used) or set the recovery option for the object (see the later section on 'Resynching an object'). Note that any changes made using WRKAPYRMT are not processed until the next time the APYRMTJRN function is started or refreshed. 31. For a volume test, do the following on the 'local' system to create the TSTAPYRMT file and start journaling. CALL PGM(TAAJRODC46) 32. On the remote system, create the same file with: CALL PGM(TAAJRODC47) 33. Use the TSTAPYRMT command with a few updates specified: TSTAPYRMT NBRUPD(50) The number of updates also causes a percentage of the updates to be used for new records and the number of deletions that will occur. With NBRUPD(50), 30 records would be added, 3 deleted, and 50 updates would occur. In some cases, the number you specify will be rounded up. 34. Start the apply function on the remote system. STRAPYRMT 35. Wait a few seconds and then check the number of records in the file on both systems with: DSPMBRD FILE(TAATSTRMT/TSTAPYRMT) Both files should have the same number of records (18). 36. End the test with: ENDAPYRMT 37. Start the apply remote process again with: STRAPYRMT This causes the new file (TSTAPYRMT) to be placed in the internal array which allows faster access when journal entries occur. 38. Use TSTAPYRMT again and specify as large a number as desired: TSTAPYRMT NBRUPD(nnnnn) 39. When the records have been applied, use DSPMBRD as previous to determine if the same number of records exist. 40. You can run as many tests as required with TSTAPYRMT. You can try some of the SNDAPYRMTE options such as SHUTDOWN, CPY, etc. 41. You can try a test where the remote system is powered down before completing all of the entries. Specify TSTAPYRMT with a large value such as NBRUPD(20000) and then power down the remote system before it has applied all of the entries. When you re-IPL, you will need to check to see if the remote journal is still active. The CHKRMTJRN TAA command (a separate tool) provides a quick solution. Enter: CHKRMTJRN JRN(TAATSTRMT/JRN1) You should see that the remote journal is not active. The system command CHGRMTJRN will allow you to set the journal to an ACTIVE state. You must know the RDB value: CHGRMTJRN RDB(xxx) JRN(TAATSTRMT/JRN1) JRNSTATE(ACTIVE) You can use CHKRMTJRN or WRKJRNA (F16) to check the status. To apply the entries that were in process when the remote system was powered down, you must use STRAPYRMT again on the remote system. After the updates are complete, you should see the same number of records on the local and remote system. 42. When finished, use ENDAPYRMT to end the apply and review the spooled files that are output. 43. If you want to try your own objects using the same demonstration: On the 'remote' system, start the function with: STRAPYRMT -- Create the same object in library TAATSTRMT on both the 'local' and 'remote' systems. The objects should be synchronized (meaning they have the same data) as if you had used Save/Restore. On the 'local' system, start journaling to the objects using STRJRNPF or STRJRNOBJ. The journal to be used is JRN1 in TAATSTRMT. On the 'local' system, change the objects. Depending on the object type, changing the data may not cause a journal entry to be forced to the journal. Journal entries are often buffered so that multiple entries can be written at one time. If you are experiencing problems, use DSPJRN on each system to see if the entries exist. See the SNDAPYRMTE OPTION(FORCE) function to force the journal entries. Even if the desired journal entries exist on both systems, be sure to wait a few seconds for the apply process to update the objects before checking the results. Check the results with: - PRTDB2 for data base objects - DSPDTAARA for data areas - DSPDTAQ for data queues If you want to simulate error conditions, see the section on 'Simulating an error condition'. 44. On the 'remote' system, to end the function, enter: ENDAPYRMT You should see a break message describing that the APYRMTJRN function has ended. 45. If you no longer need the demonstration, proceed to the next section. Cleaning up the local and remote system demonstration ----------------------------------------------------- 1. On the 'local' system, end the 'remote journaling' function by entering: WRKJRNA JRN(TAATSTRMT/JRN1) Use F16 (Work with remote journal information), and Option 14 (Inactivate) if the journal state is ACTIVE. If you changed the journal state, press F5 to ensure the journal state is INACTIVE. 2. Use F3 to exit the WRKJRNA display. 3. On the 'local' system remove the remote journaling function by entering RMVRMTJRN. RMVRMTJRN RDB(xxx) SRCJRN(TAATSTRMT/JRN1) If you are not familiar with the RDB entry, use WRKJRNA, F16 (Work with remote journaling information), and then option 5 (Display remote journal details). The RDB to use is described as 'Relational database'. 4. On the 'local' system, delete the TAATSTRMT library by entering: CALL PGM(TAAJRODC89) 5. On the 'remote' system, delete the TAATSTRMT library by entering: DLTLIB LIB(TAATSTRMT) You may need to respond 'I' to ignore the inquiry message that a journal receiver has not been saved. 6. On the 'remote' system, delete the APYRMTJRN library by entering: DLTLIB LIB(APYRMTJRN) If the library cannot be successfully deleted, recover based on the messages. APYRMTJRN Overview ------------------ Local System Remote System ------------ ------------- ********************* ********************** * * * * * - Files * * - Files * * - Data Areas * * - Data Areas * * - Data Queues * -->* - Data Queues * * * \| * * ********************** \| ******************** \| \| \| \| \| ********** \| ************ \| * * \| * * \| * SNDAPYRMTE * \| * APYRMTJRN * \| * command * \| * objects * \| * * \| * * \| ************ \| ********** \| \| *********** \| v \| * <-------- *************** \| --->* STRAPYRMT * ----------- * * \| \| * * ------->\| \| * Journal <----- \| ************ \| Listing \| * * \| \| \| \| ************** \| v ----------- \| ****** \| \| * MSGQ * \| \| ****** \| __________________ \| \| v \| ************ ************** * * * * * Journal * Some * Journal * * Receiver * ----> Communication ---->* Receiver * * * function * * ************** ************** Naming convention ----------------- When you use the CRTAPYRMTD command to create the required objects, a library must be named. The name must be 9 characters or less. The default is APYRMTJRN. You must first create this library with the CRTLIB command. The name of the library is used to name some of the created objects and jobs that will be submitted. For example, if you took the default, the subsystem that is created is named APYRMTJRN and the master job that is submitted is also named APYRMTJRN. The APYRMTJRN tool may be used to apply the entries for multiple remote journals on the same remote system. However, a separate CRTAPYRMTD command and library must be used for each journal. While the APYRMTJRN name is the default, you could name the library ABC. You must first create this library. Using the ABC name on CRTAPYRMTD would cause several objects named ABC to be created in the ABC library and the ABC 'master' job would be submitted to batch. The ABC name would have to be specified on commands such as STRAPYRMT, WRKAPYRMT, etc. The rest of the documentation assumes that you are using the default library name of APYRMTJRN. APYRMTJRN Jobs -------------- When you enter the STRAPYRMT command, the APYRMTJRN subsystem is started and the APYRMTJRN job is submitted to batch using the APYRMTJRN job queue. The APYRMTJRN job is known as the 'master' job. It accesses the objects created by CRTAPYRMTD and extracts the entries from the remote journal receiver. Many journal code/type entries (such as a save of an object) are ignored because they are not required for replicating data. The entries to be processed (such as an update to a data base record) are placed in 1-9 user spaces (USRSPC object type) that will be processed by 1-9 APYRMTJRNn apply jobs. These 'apply' jobs are submitted by the APYRMTJRN job. By default, all entries are applied by the APYRMTJRN1 job. It will always be submitted. Using the WRKAPYRMT command, you can specify which batch job should be used for any object that is being journaled. Allowing multiple 'apply' jobs allows you to spread the workload of the apply function. Using multiple apply jobs should only be considered if you are not getting enough throughput from the default apply job. Using USRSPC objects provides the fastest form of asynchronous job communication between the apply jobs. Pointers are used to write and read the data. Another batch job APYRMTJRNC is also submitted by STRAPYRMT. It is a never ending job that wakes up every 10 minutes. The intent of this job is to ensure that the other batch jobs are still active. If WRKACTJOB is used, you will normally see the APYRMTJRNC job as active with DLY-600. When the APYRMTJRNC job wakes up, it checks to see if the other batch jobs are still active. If not active, a message is sent to the message queue specified on CRT/CHGAPYRMTD if it is in BREAK mode. If not in BREAK mode, a message is sent to QSYSOPR. When ENDAPYRMT is used, the APYRMTJRNC job is ended immediately which causes an abnormal termination. However, the message to the submitter is suppressed and the job log is deleted automatically. APYRMTJRN objects ----------------- The CRTAPYRMTD command creates several objects in a library. The default library is APYRMTJRN. The following objects are created: ** APYRMTJRN SBSD. A subsystem which is used for all batch work required by the tool. The maximum number of jobs is set to NOMAX and the only pool is assigned to BASE. A standard batch routing entry is defined and a job queue entry is added for the APYRMTJRN job queue. If you need to change the attributes of the subsystem use CHGSBSD and/or the TAA tool WRKSBSD2. * APYRMTJRN JOBQ. A job queue which is used for all batch work required by the tool. The job queue is set to allow an unlimited number of batch jobs to be run simultaneously. This is important as you may have several batch 'apply' jobs that need to be activated from the job queue at the same time. * APYRMTP FILE. A physical file with one record for each object that is being journaled. The file is updated automatically when the APYRMTJRN job completes. The unique type/library/object/member information from each processed journal entry is used to create a record. The WRKAPYRMT command can be used to review the objects and change some of the controlling entries for the objects being journaled. * APYRMTL FILE. A logical over the APYRMTP file. * APYRMTJRND USRSPC. A user space object that holds the description created by CRTAPYRMTD. It also contains the last journal sequence number processed to allow for recovery. Other commands such as CHGAPYRMTD, DSPAPYRMTD, and RTVAPYRMTD also operate on the description. * APYRMTJRNE USRSPC. A user space object that holds any error information that is passed between the APYRMTJRN master job and the APYRMTJRNn apply jobs. The apply jobs post the information and the master job extracts it and then blanks out the user space. You would normally see blanks in this user space. * APYRMTJRN1 USRSPC. A user space object that holds the entries that are to be applied by the APYRMTJRN1 job. This is a large user space (16MB) providing for multiple entries to be written. The entries are written from the APYRMTJRN master job and read by the APYRMTJRN1 apply job. The user space also contains the next location that a entry should be written to by APYRMTJRN and the next location an entry has been processed from by the APYRMTJRN1 job. * APYRMTJRN2-9 USRSPC. User space objects that will be created by APYRMTJRN if additional batch jobs are required. These are also 16MB in size. The spaces are only created if you specify that additional batch jobs are needed using WRKAPYRMT. If you specify an additional batch job and then change to an existing batch job so the user space is no longer needed, the user space will remain. You may cleanup with DLTUSRSPC after ending the function with ENDAPYRMT. Commands provided ----------------- Commands that work with the description of the APYRMTJRN function all run on the 'remote' system. CRTAPYRMTD Creates the objects required by the APYRMTJRN function. The attributes defined are placed in the APYRMTJRN user space. For each journal to be processed, a separate CRTAPYRMTD command is required with a separate library. CHGAPYRMTD Changes the description of the APYRMTJRN attributes. The command can only be used interactively. It extracts the current values from the APYRMTJRND user space and uses the CHGAPYRMT2 command to prompt with the current values. This approach is used to avoid the restriction of a prompt override program attempting to access a user space and running into a QALWUSRDMN system value restriction. CHGAPYRMT2 Changes the description of the APYRMTJRN attributes. The command may be used interactively or in batch. All parameters prompt with SAME. DSPAPYRMTD Displays the attributes of the APYRMTJRN user space. DLTAPYRMTD Deletes the objects created by the CRTAPYRMTD command. RTVAPYRMTD Retrieves the attributes of a APYRMTJRN description. WRKAPYRMT Provides a work display of the objects that are known by the APYRMTJRN function. The records are stored in the APYRMTP data base file. The file is updated each time the APYRMTJRN job ends or a refresh occurs (see SNDAPYRMTE). You may change the controlling attributes for the objects being journaled, but the change will not be processed until the APYRMTJRN function is ended or refreshed. The WRKAPYRMT delete option described the wrong error if the object exists. This has been corrected. Run time commands STRAPYRMT Runs on the 'remote' system to start the APYRMTJRN subsystem and submits the APYRMTJRN job. The APYRMTJRN job will submit 1-9 apply jobs named APYRMTJRNn depending on which batch jobs (if any) you have specified to process the entries. ENDAPYRMT Runs on the 'remote' system to shutdown the APYRMTJRN function. SNDAPYRMTE Runs on the 'local' system. It sends a special journal entry (various options) to the journal that is being processed on the 'remote' system. The type of journal entry requested causes functions such as 'shutdown'. CHKACTJRN The separate tool runs on the 'local' system to check if the remote journal is still active. Security considerations ----------------------- Security is controlled by an authorization list, the use of individual authorizations, and the program adopt function. ** An authorization list (TAAAPYRMT) is shipped with the product that controls the most sensitive commands. The authorization list is shipped so that the PUBLIC user is EXCLUDE. You must be authorized to TAAAPYRMT to do the following: CRTAPYRMTD STRAPYRMT ENDAPYRMT SNDAPYRMTE The following commands are public: CHGAPYRMTD - requires CHANGE auth to a USRSPC CHGAPYRMT2 - requires CHANGE auth to a USRSPC DLTAPYRMTD - requires ALL authority to objects DSPAPYRMTD - requires USE auth to a USRSPC RTVAPYRMTD - requires USE auth to a USRSPC WRKAPYRMT - requires CHANGE auth to a USRSPC * The STRAPYRMT programs, all use the program adopt function USRPRF(OWNER) to adopt the authority of the QSECOFR owner. This allows complete access and update capability to any object while the function is running. The ENDAPYRMT and SNDAPYRMTE commands also adopt. A system operator who is authorized to the TAAAPYRMT authorization list may start and end the function without specific authorization to any of the objects. * The subsystem that is created by CRTAPYRMTD is set to AUT(USE) so that only the user who did CRTAPYRMTD may change it. * The job queue associated with the subsystem is set to AUT(EXCLUDE). This prevents a user from submitting work to this job queue which allows an unlimited number of jobs to be active. * The CRTAPYRMTD AUT parameter determines the authority to the APYRMTP file. The default is USE. The owner may authorize other users to update the file. The user spaces that are created are set to AUT(USE). A user must have CHANGE authority to change the data. APYRMTJRN Processing -------------------- When the STRAPYRMT command is entered on the 'remote' system, a library is named. A subsystem with the same name as the library is started. Assuming the library name is APYRMTJRN, the APYRMTJRN subsystem would be started and the APYRMTJRN job would be submitted to the APYRMTJRN job queue. The APYRMTJRN job first checks to see if the APYRMTJRNn jobs have completed normally. If not, these jobs are started with a special value that tells them to end when they are caught up applying journal entries. This means no new journal entries are applied until the entries that were processed by the prior APYRMTJRN job are completed. The APYRMTJRN job then reads the APYRMTP file which contains a record for each object that has had journal activity since APYRMTJRN was first used for the specified journal. On the initial use of the command, no objects are known. A table is setup within the program with an entry for each object (type/object/library/member) and an 'existence test' is made. The attributes of the object are retrieved such as the maximum record length for a data base file, the length of a data area, or the maximum entry length of a data queue. This information is updated into the table and is used when checking a journal entry to be processed. Data base entries are rejected if the record length does not match. This helps ensure that consistent object definitions exist between both the local and remote systems. Data Area and Data Queue length checking is not as strict as Data Base checking. Data Area and Data Queue journal entries do not describe the maximum length of the object, but only of the change. If the change length is less than or equal to the the remote system maximum length, the entry will be applied. The entry will be rejected if it is larger than the maximum allowed length on the remote system. Since on the initial use of the STRAPYRMT command no objects are known, all table entries are marked to be processed by the APYRMTJRN1 job. This job is always submitted to batch. The journal receiver is read by the QjoRetrieveJournalEntries API. Each journal entry contains the journal code and type, the qualified object name, the member, and relative record number (if it is a data base record entry) as well as the data (such as the record image after an update). Only those journal codes and types that impact data (such as a record update or a data area change) are processed. Special entries from the SNDAPYRMTE command are also processed (see the section on 'Send Apply Remote Entry'). When a journal code/type is to be processed, the object name from the journal entry is used in a lookup (binary search) against the table that was built at the beginning of the program. If the table entry is not found, an overflow area (another internal table) is searched. If the entry still does not exist, it is added to the overflow area. The journal entries to be processed are placed in a unique user space for each batch apply job. These user spaces (APYRMTJRN1 - APYRMTJRN9) are automatically created in the library specified by CRTAPYRMTD if the corresponding batch job is needed. Multiple entries are placed in the user spaces to allow asynchronous processing between the master job (APYRMTJRN) and the apply jobs (APYRMTJRN1 - APYRMTJRN9). When there are no more journal entries to be processed, the master job goes into a wait. An option on CRT/CHGAPYRMTD determines how long a wait occurs. When the master job wakes up after a wait, it uses the API again to see if new entries exist. The apply job accesses the user space and compares the information posted by the master job describing the next location to be written versus the information posted by the apply job for the next location to be processed. If they are the same, the apply job goes into a wait. An option on CRT/CHGAPYRMTD determines how long a wait occurs. When the locations differ, a journal entry is processed (special handling occurs when the user space is filled to its 16MB limit). When the first journal entry occurs to change the data contents of a record for a specific member, the member is opened. The member remains open for the duration of the APYRMTJRN job (unless ended by a SNDAPYRMTE option). If the member is open, you cannot allocate it, change the description of the member, initialize the member, etc. The following data base entries are processed: * Add. Does a 'write' to the file. It is possible that an error such as a 'duplicate key' would occur and the record would not be added. After a successful write, the relative record number of the inserted record is compared to the relative record number in the journal entry. An error occurs if the numbers differ. Update. Does a chain by relative record number and an update. An error is posted if the relative record number does not exist. Other errors are possible such as a 'duplicate key'. Delete. Does a chain by relative record number and a delete. An error is posted if the relative record number does not exist. Special handling occurs for PX journal types which cause an 'add' to a specific relative record number. A PX entry typically occurs when an 'add' is used in a 'reuse deleted records' type of file. The CRTJRN MINENTDTA function is supported. This provides for shorter journal entries when an update occurs. Additions are full length. Record length checking does not occur if the journal entry is minimized. Some member level changes such as INZPFM, ADDPFM, CLRPFM, RMVM, and RNMM are also handled. See the later sections on RGZPFM and MOVOBJ/RNMOBJ. Data area changes for either the full length or a partial length are processed. Both character and decimal data areas can be changed. Data Queue changes either keyed or non-keyed and with or without 'sender ID' are handled. The specific entry caused by the CLRDTAQ API is also handled. If the QRCVDTAQ program is called to receive an entry on the local system and no entry exists, no journal entry is generated. If a 'receive' request occurs on the remote system and no entry exists, no error occurs. For data base files, the apply programs use C language run time library functions to perform I/O. The first journal entry for a library/file/member establishes a pointer to the object that is used if additional journal entries occur for the same member. The files remain open to improve performance. Closing the file on the local system does not cause the file on the remote system to be closed. Leaving the files open prevents the use of certain commands on the 'remote' system. You can close a file/member on the remote system by using a SNDAPYRMTE option on the 'local' system. Ending the job closes all of the data base files. Note that the APYRMTJRN jobs are written so that they will remain active waiting for more entries to be placed into the journal or to be applied. All APYRMTJRN jobs listen for an ENDJOB command by use of the RPG SHTDN operation code. A 'shutdown' could be caused by the ENDAPYRMT command which allows you to terminate the subsystem gracefully. You may also end the subsystem by using a SNDAPYRMTE option on the local system. When the APYRMTJRN job is ended, the entries from the internal tables are written to the APYRMTP file. The next time STRAPYRMT is used, the information in the file is placed in the main table. Once there are object records in the APYRMTP file, you may use the WRKAPYRMT command to specify options on the object being applied to. Changing an option will not impact the APYRMTJRN function if it is running. However, at the next refresh or next use of STRAPYRMT, the option will be used. Note that once the object is known (at least one journal entry has caused data to be changed), a record of the object is placed in the file and table. If no additional activity to the object occurs, the file and table entry will still exist (this causes only minimal overhead as files are not opened unless activity occurs). If the object is no longer part of the application, use WRKAPYRMT to remove the record from the file. Each time the APYRMTJRN job is ended, a listing of the internal table is made. A line is printed for each known object containing a count of journal activity and any errors that have occurred (see the section on 'Error Handling'). An option exists (on CRT/CHGAPYRMTD) to have a summary listing of the activity for each apply job. SNDAPYRMTE Command (Send Apply Remote Entry) -------------------------------------------- The SNDAPYRMTE command is used on the local system to cause actions to the APYRMTJRN job that is running on the remote system. For example, a method of ending the remote system APYRMTJRN jobs and subsystem is to specify: SNDAPYRMTE JRN(xxx) OPTION(SHUTDOWN) Note there is no 'startup' function supplied by the APYRMTJRN tool to run from the local system. The STRAPYRMT command must be run on the remote system. SBMRMTCMD could be used to submit the command. In addition to 'shutdown', you may specify an option to" - Initialize the activity statistics - Print the table without ending the APYRMTJRN function - Refresh the table - End an object (stop applying changes) - Start an object (allow journal entries to be applied) - Copy an object (refresh the data) - Check the time it takes to process an entry - Force entries from the local system buffer to the journal All SNDAPYRMTE journal entries that are sent to the remote system are forced to the journal. See the SNDAPYRMTE command for specific details about each option. Commitment Control processing ----------------------------- When commitment control is used, the journal code 'C' is used by the system for special journal entries. You can review what the journal entries look like by using DSPJRN during the demonstration on a 'single system'. Commitment control was used for FILEB in TAATSTLCL. When a 'commit cycle' begins, the SC type journal entry is written for a 'start of commit'. In a normal commit operation, the SC type would be followed by journal entry 'R' codes (record change) for updates (both before and after images), puts (writes), and deletes. If the program issues a 'commit', the CM type journal entry is written to say the commit group is complete. If a rollback occurs, the system sends special entries such as DR (record deleted for rollback), BR (update before-image for rollback) to reset the data base, followed by an RB entry to say a rollback occurred. The RB entry ends the 'commit cycle'. If there is no interruption in the entries as they are processed, APYRMTJRN handles both a successful commit and a successful rollback. If however, processing is interrupted before the commit cycle is completed by either a CM or RB entry occurs, some entries would be applied to the 'remote' system without establishing a proper commit boundary. In the case where the communication line fails, the commit boundary would be correct once the communication line is brought up and APYRMTJRN begins processing the missing entries. Error handling -------------- If errors are detected during processing, the object is flagged as in error and a message is sent to the message queue specified on CRT/CHGAPYRMTD. Typical errors include: * An object does not exist to apply an entry to. The length of the journal entry does not agree with the remote file definition. For example, you have added a new field to the local file and have forgotten to change the definition on the remote system. The relative record number of an add of a new record does not agree between the local and remote systems. ** A duplicate key error has occurred. Errors are handled differently depending on the 'Recovery type' as specified using WRKAPYRMT (default is S/R'). S/R For the first error detected on an object, a message is sent to the message queue specified on CRT/CHGAPYRMTD. Once an object is marked with an 'error indication', all subsequent journal entries for the same object are bypassed. The normal recovery method would be either Save/Restore or the SNDAPYRMTE OPTION(CPY) function. If the APYRMTJRN function is shutdown and restarted, the 'error indication' will no longer exist and the journal entries will be attempted to be applied. If the object is still in error, the 'error indication' will be set again. The 'error indication' is reset by the journal entry caused by INZPFM or the QCLRDTAQ API (the API is called by the TAA CLRDTAQ command). The 'error indication' is also reset by the SNDAPYRMTE OPTION(CPY) function. EDT For serious errors (such as the object does not exist, wrong length, etc), the processing is the same as S/R. For minor errors (such as a mismatch in Relative Record numbers on an add), each error causes a message to be sent to the message queue specified on CRT/CHGAPYRMTD. Processing of additional journal entries to the same object continues. Additional errors may occur. The use of EDT is intended for the case where the object is too large to consider the use of Save/Restore (except when serious errors occur) and some form of user editing will be used to bring the files into synch. The listing which occurs at the end of the program (or by SNDAPYRMTE OPTION(PRINT)) will include a flag for those objects that do not exist and those that have had journal activity that could not be processed. If the object is marked as in error, you must get the local and remote versions of the object in synch before APYRMTJRN can be effective. Once you have the objects in synch between the local and remote systems, do either: ** If the APYRMTJRN job is running, use SNDAPYRMTE OPTION(STROBJ) to tell the APYRMTJRN job to start applying entries to the object. * If the APYRMTJRN job is not running, the journal entries will be applied normally the next time you run the STRAPYRMT command. Simulating an error condition ----------------------------- To see how APYRMTJRN handles errors, the following assumes you are using the demonstration for both the 'local' and 'remote' systems. On the 'remote' system, display the description: DSPAPYRMTD Ensure that the message queue described is in break mode. To simulate a relative record error, you could: On the 'remote' system, create a file: CRTPF FILE(TAATSTRMT/FILEX) RCDLEN(50) On the 'local' system, create the same file: CRTPF FILE(TAATSTRMT/FILEX) RCDLEN(50) On the 'local' system, enter a single record by using: EDTDBF FILE(TAATSTRMT/FILEX) When the initial prompt appears, you will be in 'add mode' because there are no records in the file. Enter one record with a value such as 'RECORD 1' and then end EDTDBF. On the 'local' system, start journaling with: STRJRNPF FILE(TAATSTRMT/FILEX) JRN(TAATSTRMT/JRN1) On the 'local' system, use EDTDBF again: EDTDBF FILE(TAATSTRMT/FILEX) When the initial prompt appears, you will be in 'display mode'. Press F9 to enter 'add mode'. Enter a second record with a value such as 'RECORD 2' and then end EDTDBF. When the apply program attempts to add a record, there will be a mismatch in the relative record numbers because the 'local' system has done an add at RR # 2 while the 'remote' system has done an add at RR # 1. You should see a break message occur. On the 'remote' system, display the records in the file using: PRTDB2 FILE(TAATSTRMT/FILEX) Note that the record in error was actually added to the file. In the case of an 'add' it cannot be determined that a mismatch occurs until the record is added. To simulate a record length error, you could: On the 'local' system, create a file: CRTPF FILE(TAATSTRMT/FILEY) RCDLEN(50) On the 'remote' system, create the same file with a different record length: CRTPF FILE(TAATSTRMT/FILEY) RCDLEN(45) On the 'local' system, start journaling with: STRJRNPF FILE(TAATSTRMT/FILEY) JRN(TAATSTRMT/JRN1) On the 'local' system, use EDTDBF and enter a single record: EDTDBF FILE(TAATSTRMT/FILEX) The apply program will sense a mismatch in the record length of the journal data and the file. You should see a break message appear. To simulate a missing object: On the 'local' system, create a data area: CRTDTAARA DTAARA(TAATSTRMT/DTAARA1) TYPE(CHAR) LEN(10) On the 'local' system, start journaling with: STRJRNOBJ OBJ(TAATSTRMT/DTAARA1) OBJTYPE(DTAARA) JRN(TAATSTRMT/JRN1) On the 'local' system, change the data area CHGDTAARA OBJ(TAATSTRMT/DTAARA1) VALUE('ABC') The apply program will sense that the object does not exist. You should see a break message appear. Managing the APYRMTJRN function ------------------------------- There are several functions that need to be considered: ** Any journals to be handled must be MNGRCV(USER). Use WRKJRNA to check for the setting and if needed, use CHGJRN to specify MNGRCV(USER). ** The 'journal state' must be kept ACTIVE. See the section on 'Keeping the remote journal active'. * The APYRMTJRN function must be started on the remote system after each IPL with the STRAPYRMT command. Consider an auto start job. You should keep the message queue specified on CRT/CHGAPYRMTD in break mode. This will quickly inform you of errors or significant events. If you choose a message queue other than QSYSOPR, consider who will manage this queue. Review the listing produced when the APYRMTJRN job completes (or by use of SNDAPYRMTE OPTION(PRINT)). This will list all of the objects that are known (have had any journal activity in the current or prior use of APYRMTJRN), whether they exist, and whether errors have occurred during processing. You should ensure that no errors were found. * Determine when to change journal receivers on the local system. This will automatically create a new receiver on the remote system. Delete old receivers on both the local and remote system. Keep the previous version online until another new receiver is added. Consider the use of the TAA MTNJRN command for both systems. Resynch objects when required (see the section on 'Re-synching an object'. The number of journal sequence numbers that may be processed by APYRMTJRN is 10 billion (9,999,999,999). Messages are provided at various points when the sequence number exceeds 9,000,000,000. See the section on 'Resetting the journal sequence numbers'. Note that though journal sequence numbers may be supported by the system to a number considerably larger than 9 billion, the APYRMTJRN tool restricts to 10 digits. Resetting the journal sequence numbers -------------------------------------- Because the APYRMTJRN tool is dependent on ascending sequence numbers, it is important that when the journal sequence numbers are to be reset, that you perform the following steps. On the 'remote' system, end the APYRMTJRN function: ENDAPYRMT On the 'local' system use CHGJRN to change to a new receiver and reset the sequence numbers. CHGJRN JRN(xxx/yyy) JRNRCV(GEN) SEQOPT(RESET) On the 'local' system, do WRKJRNA: WRKJRNA JRN(xxx/yyy) Use F15 to display the journal receivers. Delete all but the currently attached journal. Note the name of the journal receiver and library to be used later. On the 'remote' system, do WRKJRNA: WRKJRNA JRN(xxx/yyy) Use F15 to display the journal receivers. Delete all but the currently attached journal. On the 'local' system, do DSPJRN: WRKJRNA JRN(xxx/yyy) Ensure that the beginning journal sequence number is '1'. Start the APYRMTJRN job on the 'remote' system with the sequence number and new receiver name and library: STRAPYRMT LIB(lll) JRNRCV(xxx/yyy) SEQNBR(1) The new receiver should then be processed beginning at the first sequence number. Referential Integrity and Triggers ---------------------------------- Both Referential Integrity constraints and Trigger programs on the local system may cause an action against a data base file such as an add or a delete. If the file being changed is journaled, a journal entry would be passed to the remote system. If the system APYJRNCHG command is used, the system applies the entries and does not invoke the Referential Integrity or trigger function. However, since the APYRMTJRN tool is an application program, the same Referential Integrity or Trigger function on the remote system could cause the original action to be duplicated. This could result in a mismatch of relative record numbers. An option exists on CRT/CHGAPYRMTD for the handling of journal entries caused by Referential Integrity constraints and triggers. See the APYREFITG and APYTRIGGER parameters. The default is NO meaning that the entries are bypassed and not applied on the remote system. The default does not impact the original file. For example, if FILEA is changed by an application and a trigger program for FILEA causes a new record to be added to FILEB, it is the FILEB journal entry that is bypassed. The FILEA journal entry would be applied normally. If your intent in using the APYRMTJRN tool is for high availability (the ability to switch operations to the remote system), you would want the same Referential Integrity and trigger functions to be active on the remote system. You should take the default of NO. In the FILEA/FILEB example, the trigger program on the remote system would generate the new record for FILEB. If your intent in using the APYRMTJRN tool is for backup of data (you have not duplicated the program environment), you should specify YES to have the entries applied. RGZPFM ------ Because the APYRMTJRNn jobs are processing journal entries in a single job, any RGZPFM requests would hold up processing of any other journal entries for the apply job until the reorganization was complete. For this reason, a RGZPFM journal entry is bypassed and the file/member is marked as in error. No other entries will be processed until the files are re-synchronized. A message is sent to the specified message queue if a RGZPFM journal entry is found. You can re-synchronize using Save/Restore and then begin processing again by using SNDAPYRMTE OPTION(STROBJ). An alternative to RGZPFM is to use the TAA tools Compress Deleted Records (CPRDLTRCD) and Truncate Deleted Records (TRNDLTRCD). These tools allow you to reclaim deleted record space with only a brief period where the file is unusable by other jobs. See the section on 'Significant object changes'. MOVOBJ/RNMOBJ ------------- APYRMTJRN assumes a static environment. Any journal entries for MOVOBJ or RNMOBJ are flagged and the object is marked in error. See the section on 'Significant object changes'. Significant object changes -------------------------- The following describes some typical situations and solutions: ** Data Base record format change is required (such as adding a new field, changing a definition, etc). Quiesce the application on the local system to prevent any changes to the data. Use STRAPYRMT OPTION(ENDOBJ) to end applying changes to the remote system. Make the change on the local system. Use a Save/Restore approach or SNDAPYRMTE OPTION(CPY) as described in the section on 'Re-synching an object'. ** RNMOBJ or MOVOBJ is required. Quiesce the application on the local system. Use STRAPYRMT OPTION(ENDOBJ) to end applying changes to the remote system. Rename or move the object on both local and remote systems. Note there is no need to describe the new object on the remote system to APYRMTJRN. It will recognize journal entries for the newly named object and begin applying changes. You may want to delete the old name from the data base with the WRKAPYRMT command to avoid clutter. * RGZPFM is required (see the TAA Compress Deleted Records (CPRDLTRCD) tool for an alternative solution). Because the relative record numbers will be reset, CPRDLTRCD should not be used in certain applications that utilize existing relative record numbers. Quiesce the application on the local system and use SNDAPYRMTE OPTION(ENDOBJ) to prevent applying any changes on the remote system. Use RGZPFM on the local system. Use either RGZPFM on the remote system or use a Save/Restore approach or SNDAPYRMTE OPTION(CPY) as described in the section on 'Re-synching an object'. Re-synching an object --------------------- There will be instances when an object needs to be re-synched. You must describe to APYRMTJRN which technique you will be using. ** The default resynch method defined for WRKAPYRMT is 'S/R'. This means you will use the Save/Restore or SNDAPYRMTE OPTION(CPY) technique to resynch an object. ** The option for WRKAPYRMT is 'EDT' which means you will provide a manual resynch. The following describes these approaches: * Save/Restore. You would quiesce the object on the local system, and use SNDAPYRMTE OPTION(ENDOBJ) to stop applying changes. Save the object on the local system and restore it to the remote system. If the APYRMTJRN function is running, use SNDAPYRMTE OPTION(STROBJ) to reset the object to allow journal changes to occur. If APYRMTJRN is shutdown, the startup function will accomplish the same thing. ** SNDAPYRMTE OPTION(CPY). This function will refresh an object by copying the data to itself. An exclusive lock (EXCL) is required. The object and data are duplicated to the TAAWORK library, the object is cleared, and then data is copied back. The 'clear' and 'copy back' cause journal entries to flow to the remote system. The 'clear' function causes the 'error indication' to be reset so that journal entries will be applied. There is no requirement for SNDAPYRMTE OPTION(ENDOBJ) or OPTION(STROBJ). Note that for data base files, the relative record numbers will be changed if deleted records exist in the original file. You should not use this function if you are dependent on the original relative record numbers in the file. Manual correction. The typical solution would be to correct the data that is in error with a function such as EDTDBF, CHGDTAARA, etc. See the discussion on 'Comparing objects from different systems' for different solutions. Performance ----------- There are several major factors that influence performance. There are also functions you can used to tailor the performance. The number of journal entries that are actually processed. In most applications this is the number of data base add, update, and delete operations (some applications may have a large number of data queue entries or data area changes). If you are already journaling, use the TAA Print Journal Analysis (PRTJRNANL) command to get an idea of how much activity you have. Note that the number of journal entries for 'open' and 'close' is not a significant factor. APYRMTJRN only opens each file once. However, avoiding the existence of Open/Close entries is desirable as this would result in fewer entries being written to the journal, fewer entries sent across the communication line, and fewer entries to be considered by the APYRMTJRN tool. You can omit the Open/Close entries by specifying OMTJRNE(OPNCLO) on the STRJRNPF command (see also the STRJRNLIB command). * The number of objects being journaled is generally not a significant factor (maximum limit is 32,767). If the number of objects in the overflow table reaches a specific point, the program will refresh itself. This is the same function that occurs with SNDAPYRMTE OPTION(REFRESH). If an object is no longer needed in the application, there is no significant performance degradation in leaving the object in the file used by WRKAPYRMT. The object does count against the 32,767 limit. The record describing the object can be deleted from the file using WRKAPYRMT. The listing produced by the APYRMTJRN job will also provide you with information about the amount of activity for each object being journaled. * A good method of periodically checking the performance is to enter on the local system: SNDAPYRMTE JRN(xxx) OPTION(TIMSTM) This will cause messages to be sent to the message queue specified on CRT/CHGAPYRMTD when the entry is processed on the remote system. The messages describe how the APYRMTJRN job is keeping up with applying entries. See the discussion for the SNDAPYRMTE OPTION parameter. * Remote journal delivery option. Be sure you understand the DELIVERY option specified on CHGRMTJRN. ASYNC is the default and provides the best performance, but not the best recovery. * Communication line speed. There are many alternatives for this ranging from opti-connect to traditional communication lines. The communication speed can limit what the APYRMTJRN job is capable of performing. Your communication speed should not bottleneck the application. If the communication line is a bottleneck, entries may not reach the remote system and you would be exposed to a significant loss of data if the local system fails. Run priority of the batch jobs. The CRT/CHGAPYRMTD commands allow you to specify a run priority for the APYRMTJRN master job and the APYRMTJRNn apply jobs. The default is 50 (typical default for batch work). The master batch job (APYRMTJRN) may well be a bottleneck which you can improve the performance of by providing a better job priority. Time slice for the master job. CRT/CHGAPYRMTD allow you to specify the time slice that will be allowed for the master job. The default used is the standard batch value of 5 seconds. Wait time values. CRT/CHGAPYRMTD allow you to specify the wait time that will be used by the master job if no entries exist in the journal to be extracted. You may also specify the wait time for the apply jobs if no new entries exist in the user space to be processed. The listing produced from the master job will describe the number of master waits that occurred. The optional listings produced by the apply jobs will describe the number of waits for each. If you specify too low a value, you will probably see excess waits. Each wait causes overhead on your system. It is important to remember that (assuming you have enough system power), the master and apply jobs will eventually catch up with the number of entries placed in the journal. The most important consideration is to ensure that the entries cross the communication line and exist in the journal receiver on the remote system. Multiple apply jobs may be specified using the WRKAPYRMT command to request an apply job other than APYRMTJRN1. Using multiple apply jobs should only be considered if you are not getting enough throughput from the default apply job. You can determine the amount of CPU and the number of I/O Requests used for the master and apply jobs by reviewing the listings. Both values are determined just prior to final processing for each job. Therefore, this would not include the time and I/O requests required to write out the table. Multiple journals may provide a processing advantage because each journal uses a separate job to extract the entries and a separate job (or jobs) to apply them. Each journal requires a separate library be named for the CRTAPYRMTD command. This will create a separate subsystem, job queue, etc. You should not create multiple journals unless required by your application or you are bottlenecking on the job that extracts journal entries (the default name is APYRMTJRN). The subsystem created by CRTAPYRMTD uses NOMAX for the the number of jobs and the only pool is assigned to BASE. You should consider changing these to meet your requirements. Adding a new object to a running environment -------------------------------------------- If you need to add a new object to an application that is already using APYRMTJRN, you must first synchronize the object between the local and remote systems. When journaling is started to an object on the local system, APYRMTJRN will recognize journal activity and start applying the entries (the corresponding object must exist on the remote system). There is no need to tell APYRMTJRN of a new object. It will attempt to apply the journal entry to the corresponding object. Once the object is known in the APYRMTP file, you may describe options using the WRKAPYRMT command. Restarting APYRMTJRN after a normal shutdown -------------------------------------------- If APYRMTJRN is shutdown by SNDAPYRMTE or ENDAPYRMT, proper restart is to begin at the journal entry following the last entry processed. STRAPYRMT will do this by default. For every journal entry that causes a change, the sequence number of the journal entry is updated in the APYRMTJRND user space created by CRTAPYRMTD. The next time you use STRAPYRMT, this sequence number is accessed, bumped by one, and is used to begin processing. This allows you to shutdown APYRMTJRN and restart at your convenience. For this recovery to work properly, the last journal entry processed must exist in the receiver chain. If you change receivers, good practice would be to retain the previous receiver on line as part of the receiver chain. This allows the APYRMTJRN default processing to occur. If APYRMTJRN is shutdown, you change to a new receiver and delete the old receiver, you may lose entries and the last entry processed will not exist. If the journal receiver is lost, you must specify SEQNBR(FIRST) (or a specific sequence number) on STRAPYRMT command to attempt recovery. See the section on 'Recovery'. The user spaces used to hold the entries contain the location where the next entry will be placed by the master job and the next entry to be processed by the apply job. These entries are used if an abnormal shutdown occurs. Keeping the remote journal active --------------------------------- There are two considerations: * Ensuring the APYRMTJRN subsystem is active. This is generally solved by using the QSTRUPPGM system value to include the STRAPYRMT command as part of the startup of the system. There will be times when you will want to end the subsystem to perform some other task. Because a subsystem controls the work, you can use the ENDAPYRMT and STRAPYRMT commands when needed. The APYRMTJRNC job is a never ending job submitted by STRAPYRMT and wakes up every 10 minutes to see if the other jobs are still active. If not a message is sent. ** The more critical requirement is to ensure that the remote journal is in a ACTIVE 'journal state'. If the 'local' system is re-IPLed, the state of the remote journal becomes INACTIVE. There are other reasons that the remote journaling may also become inactive. The TAA command CHKRMTJRN provides a simple means of checking the 'journal state'. An escape message (TAA9895) is sent if the remote journal is not ACTIVE. The system supports two methods of activating the remote journal: * Using the WRKJRNA command, then the F16 key, and then Option 13. ** The CHGRMTJRN command can be used to change the 'journal state' such as: CHGRMTJRN JRNSTATE(ACTIVE) You should consider writing a never ending program for the local system that periodically checks remote journaling. The following describes a simple solution (you may need to tailor this code based on your experience). PGM DCL &JRNSTATE CHAR LEN(10) CHECK: CHKRMTJRN SRCJRN(yyy) MONMSG MSGID(TAA9895) EXEC(DO) /* INACTIVE / CHGRMTJRN RDB(xxx) SRCJRN(xxx) JRNSTATE(ACTIVE) MONMSG MSGID(CPF698F) / Ignore msg from remote / GOTO WAIT ENDDO / INACTIVE / MONMSG MSGID(TAA9896) EXEC(DO) /* FAILED / /* Wake up someone as the communication / / line has probably failed / SNDPGMMSG MSG('...') TOMSGQ(xxx) GOTO WAIT ENDDO / FAILED / MONMSG MSGID(TAA9897) EXEC(DO) /* CTLINACT / /* Wake up someone as the state / / indicates a problem / SNDPGMMSG MSG('...') TOMSGQ(xxx) GOTO WAIT ENDDO / CTLINACT / /* Journal state is still ACTIVE / WAIT: /* The following wakes up every 5 minutes / DLYJOB DLY(300) GOTO CHECK ENDPGM Recovery in the event of a failure ---------------------------------- Most recovery is handled automatically. For example, * If an APYRMTJRN job fails, but the remote system does not abnormally terminate, use ENDAPYRMT (or ENDSBS) to end the function. Then use STRAPYRMT. As long as the sequence numbers in the user spaces and data changes are written to disk, the function should recover without error. If the communication method between the two systems fails, recovery is attempted by the system. If recovery is unsuccessful, the communications must be restarted, but no entries are lost. There are conditions that may cause objects to become out of synch. For example, If the remote system fails, some number of journal entries may not be applied. Because applying journal entries causes asynchronous writes to disk, some entries may not exist. This situation could be minimized by journaling the objects on the remote system. If the local system fails, not every journal entry made on the local system may be passed to the remote system. If the journal receiver can be recovered, no errors should occur. If the object can be recovered, but not the journal receiver, you have probably lost some entries. This may result in a mismatch between the two systems. If this type of error occurs, you must resynch the objects. In some cases it may be necessary to start the apply process at a specific sequence number. Do the following: On the 'remote' system, end the APYRMTJRN function: ENDAPYRMT On the 'local' system use DSPJRN to determine the journal sequence number you want to start at. DSPJRN JRN(xxx/yyy) Note the sequence number, the journal receiver and library for use in the next step. Start the APYRMTJRN job on the 'remote' system with the sequence number and journal receiver name and library: STRAPYRMT LIB(lll) JRNRCV(xxx/yyy) SEQNBR(nnn) The first entry processed should be what you requested. Keeping the environment in synch -------------------------------- APYRMTJRN is limited to the data portion of: - Data Base members - Data Areas - Data Queues Any other data in objects (such as Message Queues, User Spaces, or Stream files) that are critical to your application, must be handled separately. If you are going to use the APYRMTJRN function for high availability, you must have good control over object changes, authorizations, etc. There are TAA Tools to assist in determining if you are in synch. See the section on 'Comparing objects from different systems'. Journal Codes/Types that are processed -------------------------------------- Only certain journal code/types are processed. The others are checked to be sure they are known to the processing program and ignored. For example, not every 'R' (Record) journal entry code is processed. The following are ignored as they do not impact the replication of data: IL = New increment occurred (increase in allocated space) UB = Before image (only after images are applied) BR = Before image for commit rollback When an update occurs during commitment control processing, two entries occur. The UB entry has the prior image of the record and is bypassed. The UP entry (update) is processed with the new image (the data base is changed). If a rollback occurs, two entries occur. The BR entry contains the same image as the UP entry and is bypassed. The UR entry contains the same image as the UB entry (the original data) and is processed (the data base is changed). This resets the data base to the original value. The following journal entry code/types are processed (some result in error conditions). If a code/type is not in the list, it is ignored (no action occurs). Data record changes - Journal code = R DL = Delete DR = Delete for commit rollback PT = Put (write) PX = Put to a deleted relative record number UP = Update UR = After image for commit rollback Member changes - Journal code = F CR = Clear member IZ = Initialize member MD = Delete member MM = Move member - (caused by MOVOBJ) - Rejected MN = Rename member - (caused by RNMOBJ) - Rejected RG = Reorganize member - (caused by RGZPFM) - Rejected Data Area changes - Journal code = E EA = Change of data (either full or partial) EM = Move object - Rejected EN = Rename object - Rejected Data Queue changes - Journal code = Q QC = Non-keyed data queue clear QJ = Keyed data queue clear QK = Keyed data queue sent QL = Keyed data queue received QM = Move object - Rejected QN = Rename object - Rejected QR = Non-keyed data queue received QS = Non-keyed data queue sent SNDAPYRMTE changes - Journal type = U TT = Option types Preparing for APYRMTJRN ----------------------- Because of the 32,000 byte length restriction, you should scan your objects to determine if any have a longer length. Two TAA tools are provided and would normally be submitted to batch as: SCNDBFLEN RCDLEN(32001) LIB(ALLUSR) SCNDTAQLEN MAXLEN(32001) LIB(ALLUSR) It is desirable to minimize the number of libraries that should be replicated between the local and remote systems. This will give you less to manage. Some users prefer to separate the data libraries (such as those objects being journaled) from the program libraries. This is essential for providing minimum downtime if a 'save-while-active' approach is used. Source data should probably be kept separate from the data libraries. Reducing the the number of objects in the library of objects being journaled, has no advantage from an APYRMTJRN perspective. If you have a library where all objects (that can be journaled) should be journaled, you can force journaling by: STRJRNLIB LIB(xxx) JRN(yyy) STRJRNLIB will start journaling to any objects (data base files, data areas, and data queues). The CHKJRNLIB will just check to ensure that all objects are journaled. STRJRNLIB LIB(xxx) JRN(yyy) If you want to review all objects in a library to see if they are journaled, use: WRKJRNLIB LIB(xxx) JRNOPT(xxx) The JRNOPT parameter will allow you to see those that are journaled, those that are not, or both. You must also ensure that the environments are in synch. See the section on 'Keeping the environment in synch'. If you are going to use APYRMTJRN as a high availability solution, you will probably want to journal the same objects on the remote system. You can either journal all of the time, or when cutover occurs, you can start journaling such as with STRJRNLIB. Setting up remote journaling ---------------------------- For detail information, see 'How to setup remote journaling' in the 'I/Series System information center'. The basic steps are: * Determine the libraries that will be used and the objects that will be replicated. You normally want to minimize the number of libraries involved and include only the objects that will be replicated. This may require moving of objects. Create the libraries to be replicated on the remote system. Using the same library and object names is a requirement of the APYRMTJRN tool. Create a journal receiver and journal on the local system if not already created. You can have multiple journals, but CRTAPYRMTD requires a unique library be used for each journal. Follow the instructions in the next section about 'Setting up remote journaling communications'. You must have a Relational Data Base (RDB) entry for the next step. Use the system ADDRMTJRN command to specify the remote journaling function. Specify the RDB name you entered on WRKRDBDIRE and the name of the local system journal. If the same journal and journal library name are used on the remote system, take the defaults for TGTJRN and RMTRCVLIB. Use the defaults of RMTJRNTYPE(TYPE1) and DLTRCV(NO). The DLTRCV(NO) function is important because you do not want to delete a receiver on the local system before APYRMTJRN has applied the entries. It is normally better to manage the remote receivers separately. A typical command would be: ADDRMTJRN RDB(xxx) SRCJRN(yyy/zzz) TEXT('...') * Use WRKJRNA for the local system journal and F16 to 'Work with remote journal information'. The 'Journal state' must be ACTIVE as stated in the section on 'Keeping the Remote Journal ACTIVE'. Use option 13 to activate the remote journal function (F5 must be used to see any change to the status after changing the 'journal state'). An alternate means of activating the journal is to use the CHGRMTJRN command with the JRNSTATE parameter. You must ensure that the 'Journal state' is ACTIVE in order for the remote journaling function to be functional. If you re-IPL the system or the communications line fails, you will probably need to re-activate the journal. * Synchronize the objects to be replicated from the local system to the remote system (such as a save and restore). Journal the objects on the local system if not already done. Use CRTAPYRMTD on the remote system. Name the journal that exists on the remote system. If you took the default for SRCJRN on ADDRMTJRN, the name of the journal is the same on both the local and remote system. Name a message queue that will be in break mode on the remote system so errors may be quickly reported. The default is QSYSOPR, but since this message queue may need significant attention as you begin to use APYRMTJRN, you may want a unique message queue. The message queue can be changed later with CHGAPYRMTD. * Use STRAPYRMT on the remote system to start the APYRMTJRN tool. Begin operations on the local system that cause changes to the objects being replicated. Setting up remote journaling communications ------------------------------------------- There are several solutions for how to setup communications. The following describes only a single solution: Ensure that the communications protocol you have selected to use is configured and active on both systems. You can use TCP/IP or SNA. ** Use the WRKRDBDIRE command to add the appropriate relational data base (RDB) directory entry to the local system (you may already have one). If you use TCP, the type entry must be IP. ** If you want a simple test and are using TCP/IP, enter on both the local and remote system the CHGDDMTCPA command and specify PWDRQD(NO). To utilize this setting, use ENDTCPSVR SERVER(DDM) and then STRTCPSVR SERVER(DDM). The DDM server is normally started by the system startup program when TCP/IP is started. If TCP/IP is ended, you may need to start the DDM server with the STRTCPSVR command. Back up of the remote system ---------------------------- Because the APYRMTJRN jobs are updating user spaces and data base files, you cannot perform a backup of the libraries involved if the jobs are active. Use ENDAPYRMT to shut down the subsystem and the jobs. If journal entries are still occurring, they will be added to the existing receiver. When APYRMTJRN is restarted, it will begin applying where it left off. If you are using APYRMTJRN to allow backup to occur on the remote system instead of the local, you must shutdown APYRMTJRN in order to do the backup. This presents two considerations: 1) How long will it take to do the backup as journal entries are not being applied at this time 2) How long will it take to apply the journal entries that are being held. The best solution is generally to minimize the backup time. This can be done using the system 'save-while-active' function. Consider the TAA tool SAVACT. Comparing objects from different systems ---------------------------------------- To ensure that your objects are in synch, you can save the objects on the local system and restore them on the remote system to a different library. Comparisons of the objects can then be made for both the attributes and the data. To compare the data consider: Data Base The system supports the CMPPFM command. The TAA CMPDBF command should also be considered. Compare commands are effective on relatively small files. For large files, you should consider the TAA CLCDBFHSH tool. It allows you to calculate a hash value for the records in a member and then compare the value to the hash results for the same member on the remote system. You may output a file with the results and compare with the CMPDBFHSH command. You may also use the 'block count' function to generate a hash value for segments of the file (such as every 50,000 records) and then decreasing smaller segments to help identify the records that are not the same. Data Area The TAA CMPDTAARA command may be used. Data Queue The TAA CMPDTAQE command may be used. Error numbers described in messages ----------------------------------- If an error number is described in a message, the message text is usually sufficient to determine what the problem is. In addition, when the APYRMTJRN job completes, the listing will contain a description of the errors that have occurred. The following lists the message IDs that may be produced:" 001 The length of a data base file record exceeds 32,000 bytes (maximum supported). 002 Journal activity occurred for an object that does not exist. 003 An object size (data base record length or data queue maximum entry length) exceeds 32,000 bytes. 004 The record length of a data base record has a different length than the journal entry. 005 The data queue entry length of the journal entry exceeds the maximum length described for the data queue. 006 The data area length has been exceeded by the length of the entry in the journal. 007 The add of a relative record number failed. The probable cause is: 1) The relative record number where the record was added does not agree with the relative record number of the journal entry or 2) An error such as a 'duplicate key' has occurred. The error text includes the error message ID. 010 A journal entry for a delete failed. The probable cause is the relative record number where the record was to occur does not exist or is already a deleted record. The error text includes the error message ID. 011 A journal entry for an update failed. The probable cause is: 1) The relative record number where the update was to occur does not exist or is a deleted record or 2) An error such as a 'duplicate key' has occurred. The error text includes the error message ID. 012 A command failed. The error text includes the command. 013 Unable to close a member. The error text includes the error message ID. 014 A journal entry specified a RGZPFM which is not supported by the tool. See the section on 'RGZPFM'. 015 A journal entry specified a MOVOBJ or RNMOBJ which is not supported by the tool. See the section on 'MOVOBJ/RNMOBJ'. 016 Unable to open a member. The error text includes the error message ID. 017 CHGDTAARA failed. The error text includes the error message ID. 018 The call to QSNDDTAQ failed attempting to send a data queue entry. The error text includes the error message ID. 019 The call to QRCVDTAQ failed attempting to receive a data queue entry. The error text includes the error message ID. 020 The call to the QCLRDTAQ API failed attempting to clear a data queue. The error text includes the error message ID. 021 A CLRPFM command failed. The error text includes the error message ID. 022 An INZPFM command failed. The error text includes the error message ID. 023 A RMVM command failed. The error text includes the error message ID. 024 An ADDPFM command failed. The error text includes the error message ID. 025 A mismatch in an Array ID has occurred. Inform the TAA Productivity Tools owner of the error. 026 The apply program did not recognize the journal code/type. Inform the TAA Productivity Tools owner of the error. 027 The apply program did not recognize the option from SNDAPYRMTE. Inform the TAA Productivity Tools owner of the error. 044 An unknown error has occurred. Inform the TAA Productivity Tools owner of the error. APYRMTJRN Tool escape messages you can monitor for -------------------------------------------------- A few commands send unique escape messages: STRAPYRMT TAA9891 Sequence number not found. Most of the programs do not send escape messages. Escape messages from based on functions will be re-sent. CRTAPYRMTD Command parameters CMD ----------------------------- JRN The qualified name of the journal to be processed. The library defaults to LIBL. CURLIB may also be entered. MSGQ The qualified name of the message queue to receive error messages during the running of APYRMTJRN. The default is QSYSOPR. The library defaults to LIBL. CURLIB may also be entered. JOBD The qualified name of the job description to submit the APYRMTJRN jobs with. The default is QDFTJOBD in QGPL. The library value may be LIBL or CURLIB. APYRMTLIB The library name where the objects will be created that are used during processing. The default library name is APYRMTJRN. RESET A YES/NO option for whether to reset the activity statistics each time APYRMTJRN is used. The default is YES. In most environments, the default is probably adequate. For example, if APYRMTJRN is shutdown at the end of each day, the listing produced at the end of the job will have activity statistics for the complete day. If you do not shut down APYRMTJRN for several days, you may want to use SNDAPYRMTE OPTION(PRINT) at the end of the day followed by SNDAPYRMTE OPTION(INZSTAT). If NO is entered, the statistics will continue to accumulate until SNDAPYRMTE OPTION(INZSTAT) is used. PRTAPYSTAT A YES/NO value for whether to output a separate spooled file describing the activity for each of the batch apply jobs. The default is YES, to produce a listing for each of the actual apply jobs that were active. NO may be used to prevent the listing for any batch apply job. The master apply job (default name is APYRMTJRN) which extracts the journal entries always produces a listing. FRCJOBLOG A YES/NO value for whether to force a job log for each batch job. The default is YES meaning the job log will be created even if the job ends normally. NO may be specified to prevent the job log from being output unless the job ends abnormally. APYREFITG A YES/NO value for whether to apply entries caused by a Referential Integrity constraint. The default is NO meaning the entries will be bypassed because the Referential Integrity constraints are identical between the local and remote systems. This would be normal if you are using the remote system for a high availability solution and the ADDPFCST function exists on both systems. See the tool documentation for a further explanation. YES may be specified to cause the entries to be applied. This would be normal if the remote system is used for backup and not used for high availability. APYTRIGGER A YES/NO value for whether to apply entries caused by a Trigger program. The default is NO meaning the entries will be bypassed because the Trigger programs are identical between the local and remote systems. This would be normal if you are using the remote system for a high availability solution and the ADDPFTRG function exists on both systems. See the tool documentation for a further explanation. YES may be specified to cause the entries to be applied. This would be normal if the remote system is used for backup and not used for high availability. MSTPTY The run priority of the master batch job (APYRMTJRN). The default is 50. The value must be between 01 and 99. There will always be an APYRMTJRN job running when STRAPYRMT is used. APY1PTY The run priority of the APYRMTJRN1 batch job. The default is 50. There will always be a APYRMTJRN1 job running when STRAPYRMT is used. The value must be between 01 and 99. APY2PTY The run priority of the APYRMTJRN2 batch job if any. The default is 50. The value must be between 01 and 99. APY3PTY The run priority of the APYRMTJRN3 batch job if any. The default is 50. The value must be between 01 and 99. APY4PTY The run priority of the APYRMTJRN4 batch job if any. The default is 50. The value must be between 01 and 99. APY5PTY The run priority of the APYRMTJRN5 batch job if any. The default is 50. The value must be between 01 and 99. APY6PTY The run priority of the APYRMTJRN6 batch job if any. The default is 50. The value must be between 01 and 99. APY7PTY The run priority of the APYRMTJRN7 batch job if any. The default is 50. The value must be between 01 and 99. APY8PTY The run priority of the APYRMTJRN8 batch job if any. The default is 50. The value must be between 01 and 99. APY9PTY The run priority of the APYRMTJRN9 batch job if any. The default is 50. The value must be between 01 and 99. MSTTIMSLC The time slice of the master APYRMTJRN batch job if any. The default is 5000. The value must be between 1 and 9,999,999. MSTWAITTIM The number of seconds the master APYRMTJRN batch job waits when there are no more journal entries available from the remote journal receiver. The default is 2 seconds. The value must be between 1 and 600. The lower the value, the more current you will be in updating objects on the remote system. Note that since the journal entries are placed in the journal receiver by the system, the replication of data is no safer by providing a lower value. The spooled file produced by the master job will describe the number of waits that occurred. The more waits that occur, the more overhead is performed. APYWAITTIM The number of seconds each apply batch job should wait when there are no more journal entries available from the user space to be applied. The default is 3 seconds. The value must be between 1 and 600. The lower the value, the more current you will be in updating objects on the remote system. Note that since the journal entries are placed in the journal receiver by the system and in the user space by the master job, the replication of data is no safer by providing a lower value. The spooled file optionally produced for the apply jobs will describe the number of waits that occurred. The more waits that occur, the more overhead is performed. SRCLIB The source library to use for the QATTDDS file source. The default is TAAARC. in the TAATOOL library. A specific user library may be named, but the source file must be QATTDDS. AUT The authority to be placed on the APYRMTP file which contains one record per object being journaled. The default is USE. CHANGE or EXCLUDE may be entered. DLTAPYRMTD Command parameters CMD ----------------------------- APYRMTLIB The library name where the objects exist that are used by the APYRMTJRN tool. A library must be named. STRAPYRMT Command parameters CMD ---------------------------- APYRMTLIB The library name where the objects exist that are used by the APYRMTJRN tool. The default is APYRMTJRN. JRNRCV The beginning journal receiver to use. The default is LASTPCS for the last journal receiver used. The value of CURCHAIN is used for RTVJRNE. FIRST may be specified to mean the first journal receiver in the chain. A specific journal receiver and library may be entered. SEQNBR The journal entry sequence number to begin processing with. The default is LASTPCS meaning the sequence number that is one greater than the last journal entry processed (processed means an entry that caused a change such as an update). If you have never used STRAPYRMT before, LASTPCS will be changed internally to FIRST. FIRST may be entered to mean the first entry in the first receiver of the receiver chain. If the APYRMTJRN job was shutdown, you changed to a new receiver and deleted the old receiver, the last journal entry processed will not exist in the receiver chain. If this is the case, you must specify FIRST to begin processing. TSTLIB The test library if you are running a test to apply entries to a test library on the local system. The default is NONE meaning the library found in the journal entry will be used to apply to the object. If a test library is named, the APYRMTJRN function will use the TSTLIB name instead of the name in the journal entry. This function should only be used when you are testing the APYRMTJRN function using only the local system. TSTOPTION A test option. The default is NONE meaning this is not a test. Other options allow entries for debugging. You should use NONE unless directed by the TAA Productivity Tools owner. ENDAPYRMT Command parameters CMD ---------------------------- APYRMTLIB The library name where the objects exist that are used by the APYRMTJRN tool. The default is APYRMTJRN. SNDAPYRMTE Command parameters CMD ----------------------------- JRN The qualified name of the journal on the local system that the entry will be sent to. The library defaults to LIBL. CURLIB may also be specified. The option requested will occur on the remote system. OPTION The option to be taken. STROBJ This is intended to be used after an error has occurred such as an object did not exist when journal activity occurred or a data base member got out of synch between the local and remote systems. You must enter the OBJ parameter for a specific object. Once an error has occurred, any journal entries for the object are ignored (see WRKAPYRMT for the EDT 'recovery' option that allows some continuation). You must resynch the objects first before using STROBJ. Once synchronization has been achieved you can then use STROBJ. STROBJ is not needed if the resynch occurred while APYRMTJRN was shutdown. The next use of APYRMTJRN would begin normal processing. REFRESH will also act in the same manner. Note that STROBJ is not needed if you add a new object to both the local and remote systems. As soon as any journal activity occurs, APYRMTJRN will attempt to apply the entry. A message is sent to the specified message queue when STROBJ is used. ENDOBJ This is intended to be used if you need to end applying journal entries. The object will be marked as 'in error' and any additional journal entries will be bypassed. If a file object is specified and the member was open, the member is closed. For example, a RGZPFM journal entry will cause an error. If you are going to reorganize a file on the local system, you could end applying entries on the remote system. If the internal table is refreshed or APYRMTJRN is shutdown and restarted, the object will no longer be marked as 'in error'. A message is sent to the specified message queue when ENDOBJ is used. CPY Copies the object to itself. This function is designed to synchronize the object between the local and remote system either because: 1) the object is out of synch or 2) you want to ensure it is in synch. Copying the object to itself causes journal entries to be made which flow to the remote system and are applied normally. An exclusive lock (EXCL) is required to perform the copy function. At the completion of the SNDAPYRMTE command, it is safe to resume making application changes to the object. The CPY option is only practical on small objects during peak hours. During offpeak hours, you may use CPY for larger data base objects, but you must be prepared for the performance implications of adding many entries. The TAAWORK library (on the local system) is used as a staging area for the objects being copied. The basic approach is: 1) A copy of the object is made in TAAWORK along with the current data 2) The original object is cleared 3) The data is copied back from TAAWORK to the original object. The TAAWORK version is then deleted. If the object was in error, clearing the object causes a journal entry to be made which will reset the object (STROBJ is not needed). Note that for data base files, the relative record numbers will be changed if deleted records exist in the original file. You should not use this function if you are dependent on the original relative record numbers in the file. FORCE The FORCE function cause a journal entry to be forced. This causes buffered journal entries to be forced to the journal. It performs the function of SNDJRNE FORCE(YES). The entry is ignored on the remote system. INZSTAT Initialize the statistics that are being kept for activity. This does not end the APYRMTJRN job. See also the RESET parameter on CRTAPYRMTD. PRINT Print the internal tables of the APYRMTJRN job. This allows for printing the table of known objects and overflow objects during the running of APYRMTJRN. This does not end the APYRMTJRN job. The activity statistics are not reset. The intent of the function is to allow a periodic review of activity. Note that the listings from the APYRMTJRNn jobs are not printed by this function. REFRESH Refreshes the internal table by ending the processing program and restarting it. The activity statistics are not reset. When the program is ended, the APYRMTP file is written out and then read back in again. A purpose of this option is to allow a refresh if the number of overflow entries is getting large or the amount of activity for the overflow entries is large. Refreshing provides somewhat better performance as the overflow entry table takes longer to process. Refreshing takes some time and should not be used frequently. An automatic refresh occurs if the overflow table reaches a specific number of entries. SHUTDOWN This ends the APYRMTJRN jobs in a normal manner. The internal tables are written to the APYRMTP file, a listing is created, and the subsystem is ended. TIMSTM This special entry sends three messages to the specified message queue: 1) From the master job describing when the SNDAPYRMTE command was run on the local system. Note that the time displayed on the 'remote' system will be the clock time of the 'local system'. The clocks of the local and remote system must be in synch to make the first message meaningful versus the second message. 2) From the master job describing when the SNDAPYRMTE entry was processed by the master job 3) From the apply job describing when the SNDAPYRMTE entry was processed. The time values appear in a time-stamp format. This allows a periodic review of how fast journal entries are being applied on the remote system. OBJ This is 4 part parameter for object, library, type, and member. The member value defaults to NONE. You must specify an object to be operated on for the options STROBJ, ENDOBJ, and CPY. For data areas and data queues, the member value must be NONE. For a FILE object, a member must be specified. FIRST may be used or a specific name. If FIRST is used, the name of the member is established on the local system and the specific member name will be used on the remote system (not the first member of the file). The other options (such as SHUTDOWN), require the object name, library, and type to be blank and the member value be NONE. DSPAPYRMTD Command parameters CMD ----------------------------- APYRMTLIB The library containing the objects used by APYRMTJRN. The default is APYRMTJRN. CHGAPYRMTD Command parameters CMD ----------------------------- APYRMTLIB The library containing the user space object which has the description for the APYRMTJRN job. The default is APYRMTJRN. The command may only be used interactively. The command extracts the current values from the APYRMTJRND user space and prompts using the CHGAPYRMT2 command. CHGAPYRMT2 Command parameters CMD ----------------------------- JRN The qualified name of the journal to be processed. The default is SAME. LIBL or CURLIB may be entered for the library. MSGQ The qualified name of the message queue to receive error messages during the running of the APYRMTJRN job. The default is SAME. LIBL or CURLIB may be entered for the library. JOBD The qualified name of the job description to be used. The default is SAME. APYRMTLIB The library containing the objects used by APYRMTJRN. The default is APYRMTJRN. RESET A YES/NO option for whether to reset the activity statistics each time APYRMTJRN is used. The default is SAME meaning to retain the current option. In most environments, the default of YES is probably adequate. For example, if APYRMTJRN is shutdown at the end of each day, the listing produced at the end of the job will have activity statistics for the complete day. If you do not shut down APYRMTJRN for several days, you may want to use SNDAPYRMTE OPTION(PRINT) at the end of the day followed by SNDAPYRMTE OPTION(INZSTAT). If NO is entered, the statistics will continue to accumulate until SNDAPYRMTE OPTION(INZSTAT) is used. PRTAPYSTAT Whether to print the statistics kept by each apply job (a listing always occurs for the master job). SAME is the default. YES causes the statistics to be printed for each apply job. NO prevents the statistics from being printed for each apply job. FRCJOBLOG A YES/NO value for whether to force a job log for each batch job. The default is SAME meaning to retain the current option. YES may be specified to force a job log for each of the batch jobs. NO may be specified to prevent the job log if the job completes normally. APYREFITG A YES/NO value for whether to apply entries caused by a Referential Integrity constraint. The default is SAME meaning to retain the current option. NO means the entries will be bypassed because the Referential Integrity constraints are identical between the local and remote systems. This would be normal if you are using the remote system for a high availability solution and the ADDPFCST function exists on both systems. See the tool documentation for a further explanation. YES may be specified to cause the entries to be applied. This would be normal if the remote system is used for backup and not used for high availability. APYTRIGGER A YES/NO value for whether to apply entries caused by a Trigger program. The default is SAME meaning to retain the current option. NO means the entries will be bypassed because the Trigger programs are identical between the local and remote systems. This would be normal if you are using the remote system for a high availability solution and the ADDPFTRG function exists on both systems. See the tool documentation for a further explanation. YES may be specified to cause the entries to be applied. This would be normal if the remote system is used for backup and not used for high availability. MSTPTY The run priority of the master batch job (APYRMTJRN). The default is SAME. The value must be between 01 and 99. APY1PTY The run priority of the APYRMTJRN1 batch job. The default is SAME. The value must be between 01 and 99. APY2PTY The run priority of the APYRMTJRN2 batch job if it is submitted. The default is SAME. The value must be between 01 and 99. APY3PTY The run priority of the APYRMTJRN3 batch job if it is submitted. The default is SAME. The value must be between 01 and 99. APY4PTY The run priority of the APYRMTJRN4 batch job if it is submitted. The default is SAME. The value must be between 01 and 99. APY5PTY The run priority of the APYRMTJRN5 batch job if it is submitted. The default is SAME. The value must be between 01 and 99. APY6PTY The run priority of the APYRMTJRN6 batch job if it is submitted. The default is SAME. The value must be between 01 and 99. APY7PTY The run priority of the APYRMTJRN7 batch job if it is submitted. The default is SAME. The value must be between 01 and 99. APY8PTY The run priority of the APYRMTJRN8 batch job if it is submitted. The default is SAME. The value must be between 01 and 99. APY9PTY The run priority of the APYRMTJRN9 batch job if it is submitted. The default is SAME. The value must be between 01 and 99. MSTTIMSLC The time slice of the master APYRMTJRN batch job if any. The default is SAME. The value must be between 1 and 9,999,999. MSTWAITTIM The number of seconds the master APYRMTJRN batch job waits when there are no more journal entries available from the remote journal receiver. The default is SAME. The value must be between 1 and 600. The lower the value, the more current you will be in updating objects on the remote system. Note that since the journal entries are placed in the journal receiver by the system, the replication of data is no safer by providing a lower value. The spooled file produced by the master job will describe the number of waits that occurred. The more waits that occur, the more overhead is performed. APYWAITTIM The number of seconds each apply batch job waits when there are no more journal entries available from the user space to be applied. The entries are placed in the user space by the master job. The default is SAME. The value must be between 1 and 600. The lower the value, the more current you will be in updating objects on the remote system. Note that since the journal entries are placed in the journal receiver by the system and in the user space by the master job, the replication of data is no safer by providing a lower value. The spooled file optionally produced for the apply jobs will describe the number of waits that occurred. The more waits that occur, the more overhead is performed. WRKAPYRMT Command parameters CMD ---------------------------- APYRMTLIB The library containing the objects used by APYRMTJRN. The default is APYRMTJRN. EXIST A selection option for whether you want to display an object if it exists. The default is ALL to see both objects that exist and those that do not. Once an object has a journal entry to be applied, a record is kept in the APYRMTP file. If the object is deleted, the record still exists. YES may be entered to see only those objects that still exist. NO may be entered to see only those that no longer exist. You can use the delete option on the work display to clean up old objects. BATCHJOB A selection option for whether you want to see only those objects that will be applied by a specific batch job. ALL is the default to display all records regardless of which batch job does the apply. A 1-9 value may be entered to display only those jobs that will be applied by APYRMTJRN1 - APYRMTJRN9. RTVAPYRMTD Command parameters CMD ----------------------------- APYRMTLIB The library containing the objects used by APYRMTJRN. The default is APYRMTJRN. JRN The journal name. This is an optional parameter that if used must be specified as CHAR LEN(10). JRNLIB The journal library name. This is an optional parameter that if used must be specified as CHAR LEN(10). MSGQ The message queue assigned to the APYRMTJRN function. This is an optional parameter that if used must be specified as CHAR LEN(10). MSGQLIB The message queue library assigned to the APYRMTJRN function. This is an optional parameter that if used must be specified as CHAR LEN(10). SBSD The subsystem assigned to the APYRMTJRN function. This is an optional parameter that if used must be specified as CHAR LEN(10). SBSDLIB The subsystem library assigned to the APYRMTJRN function. This is an optional parameter that if used must be specified as CHAR LEN(10). JOBQ The job queue assigned to the APYRMTJRN function. This is an optional parameter that if used must be specified as CHAR LEN(10). JOBQLIB The job queue library assigned to the APYRMTJRN function. This is an optional parameter that if used must be specified as CHAR LEN(10). JOBD The job description assigned to the APYRMTJRN function. This is an optional parameter that if used must be specified as CHAR LEN(10). JOBDLIB The job description library assigned to the APYRMTJRN function. This is an optional parameter that if used must be specified as CHAR LEN(10). RESET The reset option assigned to the APYRMTJRN function. A YES or NO value is returned. This is an optional parameter that if used must be specified as CHAR LEN(4). PRTAPYSTAT The 'print apply job statistics' option to the APYRMTJRN function. A YES or NO values will be returned. This is an optional parameter that if used must be specified as CHAR LEN(4). LSTSEQNBR The last journal sequence number processed. This is an optional parameter that if used must be specified as CHAR LEN(10). LSTJRNRCV The last journal receiver processed. This is an optional parameter that if used must be specified as CHAR LEN(10). LSTJRNRCVL The library of the last journal receiver processed. This is an optional parameter that if used must be specified as CHAR LEN(10). FRCJOBLOG The 'force job log' option to the APYRMTJRN function. A YES or NO value will be returned. This is an optional parameter that if used must be specified as CHAR LEN(4). APYREFITG The 'apply referential integrity entries' option to the APYRMTJRN function. A YES or NO value will be returned. This is an optional parameter that if used must be specified as CHAR LEN(4). APYTRIGGER The 'apply trigger entries' option to the APYRMTJRN function. A YES or NO value will be returned. This is an optional parameter that if used must be specified as CHAR LEN(4). MSTPTY The run time priority assigned to the master batch job. A value between 01 and 99 will be returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY1PTY The run time priority assigned to the APYRMTJRN1 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY2PTY The run time priority assigned to the APYRMTJRN2 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY3PTY The run time priority assigned to the APYRMTJRN3 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY4PTY The run time priority assigned to the APYRMTJRN4 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY5PTY The run time priority assigned to the APYRMTJRN5 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY6PTY The run time priority assigned to the APYRMTJRN6 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY7PTY The run time priority assigned to the APYRMTJRN7 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY8PTY The run time priority assigned to the APYRMTJRN8 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). APY9PTY The run time priority assigned to the APYRMTJRN9 batch job. A value between 01 and 99 is returned. This is an optional parameter that if used must be specified as CHAR LEN(2). MSTTIMSLC The time slice assigned to the master APYRMTJRN batch job. A value from 1 to 9,999,999 milliseconds (9999.999 seconds) is returned. This is an optional parameter that if used must be specified as CHAR LEN(7). MSTWAITTIM The number of seconds the master job should wait when there are no more entries. A number between 1 and 999 is returned. This is an optional parameter that if used must be specified as CHAR LEN(3). APYWAITTIM The number of seconds the apply jobs should wait when there are no more entries. A number between 1 and 999 is returned. This is an optional parameter that if used must be specified as CHAR LEN(3). TSTLIB The name of the test library (if any) that is being used on the local system to simulate remote journaling. This is an optional parameter that if used must be specified as CHAR LEN(10). CHKJOB The qualified name (job/user/jobnbr) of the Check Job (APYRMTJRNC) that was submitted. This is an optional parameter that if used must be specified as CHAR LEN(26). TSTAPYRMT Command parameters CMD ---------------------------- NBRUPD The number of updates to be performed. The number of updates also determines the number of adds and deletes based on a percentage. In some cases the number you enter may be rounded up. Restrictions ------------ See the section on 'Considerations'. Prerequisites ------------- The following TAA Tools must be on your system: CHGUSRSPC Change user space CHKALLOBJ Check ALLOBJ special authority CHKOBJ2 Check object 2 CHKOBJ3 Check object 3 CLRDTAARA Clear data area CLRDTAQ Clear data queue CLRUSRSPC Clear user space CMPDBF Compare data base file CMPDTAARA Compare data area CMPDTAQE Compare data queue entry CPYBCKDTAQ Copy back datq queue CRTDUPPF Create duplicate PF CRTUSRSPC Create user space CVTDAT Convert date EDTVAR Edit variable HLRMVMSG HLL Remove message MOVCHRDEC Move character to decimal RPGSTSDS RPG status data structure RSNLSTMSG Resend last message RTVDAT Retrieve date RTVDBFA Retrieve data base file attributes RTVDTAARAD Retrieve data area description RTVDTAQD Retrieve data queue description RTVMSGQA Retrieve message queue attributes RTVSBMJOB Retrieve submitted job RTVTIMSTM2 Retrieve time stamp 2 RTVUSRSPC Retrieve user space RTVSBSD Retrieve subsystem description RTVSYSVAL3 Retrieve system value 3 RTVUSRSPC Retrieve user space RTVVALA Retrieve value attributes UNADOPT Unadopt authority SNDCOMPMSG Send completion message SNDDIAGMSG Send diagnostic message SNDDTAQ Send data queue SNDESCMSG Send escape message SNDSTSMSG Send status message TAAARC TAA Archive UPDPFILE Update PF file Implementation -------------- None, the tool is ready to use. Objects used by the tool ------------------------ Object Type Attribute Src member Src file ------ ---- --------- ---------- ---------- STRAPYRMT CMD TAAJROD QATTCMD SNDAPYRMTE CMD TAAJROD2 QATTCMD CRTAPYRMTD CMD TAAJROD3 QATTCMD DLTAPYRMTD CMD TAAJROD4 QATTCMD DSPAPYRMTD CMD TAAJROD5 QATTCMD CHGAPYRMT2 CMD TAAJROD6 QATTCMD WRKAPYRMT CMD TAAJROD7 QATTCMD RTVAPYRMTD CMD TAAJROD8 QATTCMD ENDAPYRMT CMD TAAJROD9 QATTCMD CHGAPYRMTD CMD TAAJROD10 QATTCMD TSTAPYRMT CMD TAAJROD12 QATTCMD TAAJRODC PGM CLP TAAJRODC QATTCL TAAJRODC2 PGM CLP TAAJRODC2 QATTCL TAAJRODC3 PGM CLP TAAJRODC3 QATTCL TAAJRODC4 PGM CLP TAAJRODC4 QATTCL TAAJRODC5 PGM CLP TAAJRODC5 QATTCL TAAJRODC6 PGM CLP TAAJRODC6 QATTCL TAAJRODC7 PGM CLP TAAJRODC7 QATTCL TAAJRODC8 PGM CLP TAAJRODC8 QATTCL TAAJRODC9 PGM CLP TAAJRODC9 QATTCL TAAJRODC10 PGM CLP TAAJRODC10 QATTCL TAAJRODC12 PGM CLP TAAJRODC12 QATTCL TAAJRODC24 PGM CLP TAAJRODC24 QATTCL TAAJRODC27 PGM CLP TAAJRODC27 QATTCL TAAJRODC31 PGM CLP TAAJRODC31 QATTCL TAAJRODC32 PGM CLP TAAJRODC32 QATTCL TAAJRODC35 PGM CLP TAAJRODC35 QATTCL TAAJRODC41 PGM CLP TAAJRODC41 QATTCL TAAJRODC42 PGM CLP TAAJRODC42 QATTCL TAAJRODC43 PGM CLP TAAJRODC43 QATTCL TAAJRODC44 PGM CLP TAAJRODC44 QATTCL TAAJRODC45 PGM CLP TAAJRODC45 QATTCL TAAJRODC46 PGM CLP TAAJRODC46 QATTCL TAAJRODC47 PGM CLP TAAJRODC47 QATTCL TAAJRODC49 PGM CLP TAAJRODC49 QATTCL TAAJRODC54 PGM CLP TAAJRODC54 QATTCL TAAJRODC55 PGM CLP TAAJRODC55 QATTCL TAAJRODC56 PGM CLP TAAJRODC56 QATTCL TAAJRODC59 PGM CLP TAAJRODC59 QATTCL Objects used by the tool - Continued ------------------------------------ TAAJRODC61 PGM CLP TAAJRODC61 QATTCL TAAJRODC62 PGM CLP TAAJRODC62 QATTCL TAAJRODC81 PGM CLP TAAJRODC81 QATTCL TAAJRODC82 PGM CLP TAAJRODC82 QATTCL TAAJRODC83 PGM CLP TAAJRODC83 QATTCL TAAJRODC89 PGM CLP TAAJRODC89 QATTCL TAAJRODR7 PGM RPG TAAJRODR7 QATTRPG TAAJRODR12 PGM RPG TAAJRODR12 QATTRPG TAAJRODR41 PGM RPG TAAJRODR41 QATTRPG TAAJRODR42 PGM RPG TAAJRODR42 QATTRPG TAAJRODR43 PGM RPG TAAJRODR43 QATTRPG TAAJRODR45 PGM RPG TAAJRODR45 QATTRPG TAAJRODR48 PGM RPG TAAJRODR48 QATTRPG TAAJRODR55 PGM RPGLE TAAJRODR55 QATTRPG TAAJRODR61 PGM RPGLE TAAJRODR61 MODULE RPGLE TAAJRODR61 QATTRPG TAAJRODR71 MODULE RPGLE TAAJRODR71 QATTRPG RPGLE TAAJRODR72 QATTRPG TAAJRODR83 PGM RPG TAAJRODR83 QATTRPG TAAJRODL FILE LF TAAJRODL QATTRPG TAAJRODM FILE PF TAAJRODP QATTRPG TAAJRODP FILE PF TAAJRODP QATTRPG TAAJRODQ FILE PF TAAJRODQ QATTRPG TAAJRODS FILE PF TAAJRODS QATTRPG TAAJRODT FILE PF TAAJRODT QATTRPG TAAJRODD FILE DSPF TAAJRODD QATTRPG TAAJRODE FILE DSPF TAAJRODE QATTRPG APYRMTJRN DTAARA TAAJRODP is used as the model file when creating the APYRMTP file. The TAAJRODM file is used as an externally described data structure of the internal tables. The APYRMTJRN DTAARA is for use with the TAA Productivity Tools owner to assist when debugging is needed. Structure --------- STRAPYRMT Cmd TAAJRODC CL pgm - Submits TAAJRODC55 (Calls if INTER2) Adopts - Checks AUTL using UNADOPT TAAJRODC35 CL pgm Sbmtd by TAAJRODC - Checks active batch jobs Adopts - Job is APYRMTJRNC TAAJRODC55 CLLE pgm Submitted or called from TAAJRODC Adopts - Checks AUTL using UNADOPT Starts NEW activation group TAAJRODC54 CLLE Pgm - Check for recovery of previous use Uses CALLER activation group Calls TAAJRODR61 if recovery is needed TAAJRODC56 CLLE Pgm - Creates user spaces and sbm TAAJRODR61 for each required apply job Uses CALLER activation group TAAJRODR55 RPGLE Pgm - Master program - Extracts from JRNRCV Uses CALLER activation group Submits TAAJRODR61 unless INTER2 test TAAJRODC31 CLLE Pgm - Used for various commands (SNDPGMMSG) Uses CALLER activation group TAAJRODC59 CLP Pgm Submitted by TAAJRODC55 for REFRESH Adopts - Checks AUTL using UNADOPT Does STRAPYRMT TAAJRODR61 - ILE Pgm - Applies entries for the APYRMTJRNn job Adopts Starts NEW activation group TAAJRODR61 - RPGLE Mod - Main function TAAJRODC61 CLLE Pgm - Sets run priority, returns values Checks AUTL using UNADOPT Uses CALLER activation group TAAJRODC62 CLLE Pgm - Sends error messages during recovery Uses CALLER activation group TAAJRODC32 CLLE Pgm - Performs CL functions Uses CALLER activation group TAAJRODR71 - RPGLE Mod - Interface to C file routines TAAJRODR72 - RPGLE Copy routines for TAAJRODR71 The TAAJRODR61 structure is submitted for each of the APYRMTJRNn jobs. Structure - Continued --------------------- SNDAPYRMTE Cmd TAAJRODC2 CL pgm CRTAPYRMTD Cmd TAAJRODC3 CL pgm TAAJRODC24 CL Pgm DLTAPYRMTD Cmd TAAJRODC4 CL pgm DSPAPYRMTD Cmd TAAJRODC5 CL pgm TAAJRODD DSP file CHGAPYRMTD Cmd TAAJRODC10 CL pgm CHGAPYRMT2 Cmd TAAJRODC6 CL pgm TAAJRODC24 CL Pgm WRKAPYRMT Cmd TAAJRODC7 CL pgm TAAJRODR7 RPG pgm TAAJRODE DSP file TAAJRODC27 CL pgm RTVAPYRMTD Cmd TAAJRODC8 CL pgm ENDAPYRMT Cmd TAAJRODC9 CL pgm TSTAPYRMT Cmd TAAJRODC12 CL pgm TAAJRODR12 RPG pgm Structure - Continued --------------------- Test on local system with simulated library TAAJRODC41 CL Pgm Create libraries (TAATSTRMT and TAATSTSIM) TAAJRODR41 RPG Pgm to add records to FILEA TAAJRODC42 CL Pgm Update objects TAAJRODR42 RPG Pgm Update objects TAAJRODR48 RPG Pgm Update objects using commit TAAJRODC43 Compare results TAAJRODC49 Delete libraries Additional volume test programs TAAJRODC44 Creates n TSTFnnn files in both libraries eg CALL TAAJRODC44 PARM('010') creates 10 files TAAJRODC45 Writes n records to the TSTFnnn files TAAJRODR45 RPG to write to TSTFnnn files eg CALL TAAJRODC45 PARM('00050') writes 40 records Test using both local and remote system TAAJRODC81 Create local library TAATSTRMT and objects TAAJRODC82 Create remote library TAATSTRMT and objects TAAJRODC83 Update objects in local library TAAJRODR83 Update objects in local library TAAJRODC89 Delete local test library

APYRMTJRN       APPLY REMOTE JOURNAL                   TAAJROD


The Apply  Remote Journal  tool provides  'real time' data  replication
to a  remote system using  the system remote journaling  support.  Only
data  from  data base  file members,  data areas,  and data  queues are
supported.   The function  may be  used  for a  variety of  application
needs.  If  used for high availability, you  have the responsibility of
keeping  the environment in synch (such  as changes to programs, object
attributes, etc).


              ****************************************
              *                                      *
              *    If you are considering the use    *
              *    of this tool, check with the      *
              *    TAA Productivity Tools owner.     *
              *    You will be kept on the list      *
              *    for significant changes and       *
              *    fixes for APYRMTJRN.              *
              *                                      *
              ****************************************

The system remote  journaling support  allows a journal  receiver on  a
local  system to  be  replicated  to a  journal  receiver  on a  remote
system.   The  system APYJRNCHG  command  cannot be  used to  apply the
entries because  the apply  may  only be  done  to the  original  file.
(The system  assigns a unique  journal ID (JID)  for each file  that is
journaled which  includes an identification of  the originating system.
If  the JID does  not match between  the file and  the journal entries,
APYJRNCHG cannot be used).

The TAA  Start  Apply Remote  (STRAPYRMT) command  runs  on the  remote
system  as an  application program  to  apply the  entries.   STRAPYRMT
uses  batch jobs  to extract  the journal entries  and applies  them to
corresponding objects on  the remote system.   The same  library/object
names must be used on the remote system.

Because the  APYRMTJRN tool only handles  the data portion  of objects,
it  is  only effective  for  high  availability if  you  have  a fairly
static environment.   This  means that  programs, display  files,  data
base  file attributes,  authorizations, etc  do  not change  frequently
and you  have good control over  the changes.  The  APYRMTJRN tool does
not  replicate  changes  such  as  CHGPF,  GRTOBJAUT,  etc.    You must
replicate these changes yourself on the remote system.

You can use  APYRMTJRN to just  replicate the data  to a remote  system
if you are only interested in real time backup of the data.

The  APYRMTJRN tool supplies  its own  subsystem and  job queue.   This
provides a convenient method of starting and ending the function.

Major requirements
------------------

  **   Prepare  for  remote  journaling.    Consider  what  objects and
       libraries will be used.   Journal the  objects that you want  to
       replicate  the  data  for.     See  the  section  on  'Preparing
       APYRMTJRN'.

  **   Synchronize  the objects between  the local  and remote systems.
       This normally means that  you end the  application on the  local
       system,  do a  save of  the  objects, and  restore  them to  the
       remote system.   See the  section on 'Preparing  for APYRMTJRN'.

  **   Set  up remote journaling on the  local/remote systems.  See the
       section on 'Setting up remote journaling'.

  **   Enter the STRAPYRMT  command on the  remote system to begin  the
       function.   This causes  the APYRMTJRN  subsystem to  be started
       and the APYRMTJRN jobs to be submitted.

  **   Monitor  the results.  This includes  reviewing an error message
       queue and spooled output from APYRMTJRN.

  **   Keep the environments in synch.   This means you must  replicate
       program  changes,  authorizations,  etc.   See  the  section  on
       'Keeping the environment in synch'.

Considerations
--------------

  **   Data  base  files  up  to  32,000  bytes  in record  length  are
       supported including  null  values and  variable  length  fields.
       The system  supports a  maximum length  of 32,766.   Because  of
       the  32K restriction,  it is  unlikely that  BLOB and  CLOB data
       types could be used.

  **   Data  queue entries  up to 32,000  bytes (as  the maximum length
       defined  for  the  data  queue)  are  supported.     The  system
       supports a maximum  length of 64,512.  Both  keyed and non-keyed
       data queues are supported as well as 'sender ID'.

  **   Data areas of any size or type are supported.

  **   Stream files (from the IFS) are not supported.

  **   The  CRTJRN MINENTDTA(*YES)  for 'minimize entry  specific data'
       is supported.

  **   Up  to  32,767  different  objects  (type/library/object/member)
       can be processed from a single journal.

  **   The object and  library names to be replicated must  be the same
       on the local and remote system.

  **   Special   journal  entries   for  commitment  control   are  not
       considered.  The journal entries  are processed as they  appear.
       No attempt  is made to  buffer the entries  and apply them  only
       if  a commitment  boundary is  reached.   If a  rollback occurs,
       journal  entries will  exist and will  be processed  to roll the
       data back.   See  the  later discussion  of 'Commitment  Control
       processing'.

  **   For Referential  Integrity and Trigger handling  see the section
       on 'Referential Integrity and Triggers'.

  **   The  minimum release  is V5R1, but  the local  and remote system
       may be on different releases.

  **   The number of entries  to be processed is  only limited by  your
       systems capability to apply them.

See  the  section  on  'Preparing  for  APYRMTJRN'  for  assistance  in
checking for the limits imposed by the tool and other help.

Demonstrating the APYRMTJRN function on a single system
-------------------------------------------------------

You  can take  the APYRMTJRN  tool for a  20 minute  'test drive'  on a
single system  by  using  some  supplied test  programs.    The  remote
system is simulated by  using a different library on  the local system.

A  second  demonstration  exists (described  later)  that  uses both  a
local   and  remote   system.     The  second   demonstration  requires
additional setup to use.

It is highly recommended that  you use these demonstrations to  gain an
overall understanding  of remote journaling and how  the APYRMTJRN tool
operates.

Using  the  single system  demonstration  is the  simplest  version and
should  assist  you  in  understanding  the  documentation  and  detail
functions.

To see the  full text of messages,  you may prefer to  operate from the
full command entry display.

            CALL           PGM(QCMD)

Do the following steps all on the 'local' system.

  1.   Ensure  the   TAATOOL  library  is  on   your  library  list  by
       entering:

            EDTLIBL

       If the TAATOOL library does not exist, add it:

  2.   Ensure the  libraries  APYRMTJRN, TAATSTLCL,  and  TAATSTSIM  do
       not exist.

             DSPLIB       LIB(APYRMTJRN)
             DSPLIB       LIB(TAATSTLCL)
             DSPLIB       LIB(TAATSTSIM)

       If  any  of  the   libraries  exist  from  a  prior   use  of  a
       demonstration and you want to start over, enter:

             CALL      PGM(TAAJRODC49)

  3.   To set up the environment, enter the command:

             CALL      PGM(TAAJRODC41)

       The TAAJRODC41  program will create the 3  libraries and various
       objects.

         --   The  TAATSTLCL library contains the  objects on the local
              system that  will be replicated  to the simulated  remote
              system.    Since  these  objects  must  be  journaled,  a
              journal  and  journal  receiver are  also  placed  in the
              library (they could be in a different library).

              Display the 'local' library with:

                    DSPLIB        LIB(TAATSTLCL)

              The journal  and journal  receiver are  used to  simulate
              remote journaling.

                    RCV0001    *JRNRCV
                    JRN1       *JRN

              You should also  see the following objects  which will be
              replicated:

                    DTQKEYED   *DTAQ      Keyed (no entries)
                    DTQNONKEY  *DTAQ      Non-keyed (no entries)
                    DTQ2       *DTAQ      Second non-keyed (no entries)
                    DSPOBJDP   *FILE      Created by DSPOBJDP OUTFILE
                                             No data exists
                    FILEA      *FILE      Small amount of data
                    FILEB      *FILE      Small amount of data
                    DTAARAC    *DTAARA    Character type
                    DTAARAD    *DTAARA    Decimal type

              The  variety of  object types provides  a good  sample of
              the replication capability of the APYRMTJRN tool.

              When CRTJRN is  used, the default  for MNGRCV is  *SYSTEM
              meaning the system  will manage the change  of receivers.
              In  some  cases   the  system  will  reset  the  sequence
              numbers  which will prevent  the APYRMTJRN from operating
              properly.  Therefore,  any journals that  are to be  used
              should  be specified  as *USER  managed.   While  this is
              not  critical for  the demonstration,  you should  get in
              the habit of specifying MNGRCV(*USER).

                  CHGJRN     JRN(TAATSTLCL/JRN1) MNGRCV(*USER)

         --   The TAATSTSIM  library  contains  the  objects  that  are
              simulated to be on the remote system.

              Display the simulated 'remote' library with:

                   DSPLIB        LIB(TAATSTSIM)

              The data base,  data area, and data queue  objects in the
              TAATSTLCL  and TAATSTSIM  libraries  are identical.   The
              objects exist as  if you synchronized  them using a  save
              and restore.

         --   The APYRMTJRN  library contains  the controlling  objects
              created   by   the   Create  Apply   Remote   Description
              (CRTAPYRMTD)  command.   The library  would exist  on the
              remote system in an  actual use of the tool, but  for the
              test function,  the library will be on  the local system.

              Display the APYRMTJRN library:

                  DSPLIB     LIB(APYRMTJRN)

              The  APYRMTJRN library  includes  a unique  subsystem and
              job queue to simplify  starting and ending the  APYRMTJRN
              function.

              Data base  and user  space (*USRSPC)  objects also  exist
              which  contain control information  and will  be used for
              communication between the apply jobs.

              The message queue TSTMSGQ exists  which is set to  *BREAK
              mode  for  the   demonstration.    A  message   queue  is
              required  by  APYRMTJRN   (QSYSOPR  is  the  default)  to
              provide  for a quick indication  of any problems that may
              arise.  The message queue can be in any library.

  4.   To  start the  APYRMTJRN  function  and  cause  changes  to  the
       objects being journaled, enter the command:

             CALL          PGM(TAAJRODC42)

       This causes  the STRAPYRMT  command to be  run which  starts the
       APYRMTJRN   subsystem.     Two  batch  jobs   are  automatically
       started.  Changes are made to the objects being journaled.

  5.   Use WRKSBS to display the active subsystems:

             WRKSBS

       Use Option 8  to display the jobs  for the APYRMTJRN  subsystem.
       You  should  see  the  batch  jobs  APYRMTJRN,  APYRMTJRN1,  and
       APYRMTJRNC.

       The  APYRMTJRN  job  extracts  the  entries  from the  simulated
       journal receiver.    The  APYRMTJRN1 job  applies  the  entries.
       There can  only be  one APYRMTJRN  job per  remote journal,  but
       you can have up to 9 jobs which apply the entries.

       APYRMTJRNC is  a special job that wakes up  every 10 minutes and
       checks  if the other  batch jobs are  still active.   If not, it
       sends   a   message  to   the   message   queue   specified   on
       CRT/CHGAPYRMTD if  it is in *BREAK  mode.  If the  message queue
       is  not in *BREAK mode,  the same message is  sent to QSYSMSG if
       it exists and QSYSOPR if it does not.

       Use F3 to exit the WRKSBS display.

  6.   All of  the  objects  intended for  replication  from  TAATSTLCL
       were  changed by  the TAAJRODC42  program  which caused  journal
       entries  to  be  made.    The  tool  has already  applied  these
       entries  to  the  corresponding  objects  in  TAATSTSIM.     The
       following processing has occurred:

       The *DTAARA objects have changed in value.

       The *DTAQ types  have had entries  sent and received  from them.

       The data base files have been changed

          - A DSPOBJD OUTFILE function has added records to DSPOBJDP
          - FILEA has had an update, a delete, and an add
          - FILEB has had an update, a delete, and an add using
              commitment control and then the same functions were
              rolled back by a de-commit (RPG ROLBK operation)

  7.   Compare the objects and their data by entering:

             CALL      PGM(TAAJRODC43)

       Error  messages  will be  sent  if  any of  the  objects do  not
       match.

  8.   A  spooled file has  been generated for each  of the data queues
       and data base  files that were compared.   You can review  these
       with  WRKSPLF, but if  the entries  compared properly,  there is
       not much benefit.

  9.   To review the entries that exist in the journal, enter:

             DSPJRN    JRN(TAATSTLCL/JRN1)

       APYRMTJRN  retrieves  every journal  entry,  but  only processes
       some  of the  entry  types  and  codes.    See  the  section  on
       'Journal Codes/Types that are processed'.

  10.  To end the APYRMTJRN function, enter the command:

             ENDAPYRMT

       You should  see a  break message  that describes  that APYRMTJRN
       is  ending.    Both the  APYRMTJRN  master  job, the  APYRMTJRN1
       apply  job,  and  the  APYRMTJRNC  job  will  end  after  a  few
       seconds.     The  default   of  FRCJOBLOG(*NO)   was  taken   on
       CRTAPYRMTD so no job logs should exist.

  11.  Verify that the subsystem is no longer active using:

             WRKSBS

  12.  Review the spooled files created by each job.

             WRKSPLF

       The  APYRMTJRN spooled  file  (may appear  after  the APYRMTJRN1
       spooled  file) is  standard and  reflects the  processing of the
       APYRMTJRN job.

       The  APYRMTJRN1  spooled  file  is  optional  and  reflects  the
       processing of the APYRMTJRN1 job.

  13.  When APYRMTJRN completes,  a data base file is  written out with
       the  objects that were  being journaled.   Note that  you do not
       have to  describe what  is  be replicated  with APYRMTJRN.    It
       assumes that every  journal entry that causes a  data change has
       a corresponding object to be updated.

       To  see the file that  was written, enter the  Work Apply Remote
       (WRKAPYRMT) command:

             WRKAPYRMT

       This will describe the objects that  are now known to the  tool.

         --   Option 5 lets you review the detail information.

         --   Option 2 lets you change the default options:

              You can specify which  batch apply job (1 -  9) should be
              used the  next time you use the  APYRMTJRN function.  The
              default  is  1  for  the  APYRMTJRN1  apply  job.   Using
              multiple batch jobs  should only be  done if you are  not
              getting enough throughput from the default apply job.

              You can specify  how to 'recover' the object  if a simple
              error  occurs (such  as attempting  to update  a Relative
              Record number  which does  not exist).    The default  is
              *S/R meaning  that you will  resynch the object  by doing
              a  Save and Restore  or by use  of the Send  Apply Remote
              Entry (SNDAPYRMTE) command using OPTION(*CPY).

              You may specify  *EDT which  means you  will resynch  the
              object by  changing it on  the remote  system such as  by
              using  the TAA Edit  Data Base  File (EDTDBF)  command to
              change  individual  data base  records.   This  may  be a
              better technique to  choose if there  are many data  base
              records in  a file and the Save/Restore  process would be
              too  long to be  practical.  See the  later discussion of
              'Re-synching an object'.

              While the major  use of the *EDT  option is intended  for
              data base  files, it may also  be used for data  areas or
              data queues.

              Note  that on  the WRKAPYRMT  main  display, the  F11 key
              may be  used  to alternate  between  a display  of  which
              batch apply program to use and the recovery type.

         --   Option 4  will let you  delete the record  describing the
              object.   The intent of the function  is to allow cleanup
              if an object no longer exists.

              If  you  accidentally  delete  an  object  that  is still
              being used, no  error will occur.   The tool will add  an
              entry  for the  object if  any journaling  activity takes
              place.

       WRKAPYRMT  can   be  entered  at  anytime,  but  any  change  in
       definition will not  be used  until the next  time STRAPYRMT  is
       used or a refresh occurs.

  14.  To review  the APYRMTJRN  description, enter  the Display  Apply
       Remote Description (DSPAPYRMTD) command:

             DSPAPYRMTD

       This  describes the control  information in  the APYRMTJRND user
       space in  library  APYRMTJRN.    Most  of  the  information  was
       specified   on  the   CRTAPYRMTD  command   (run   for  you   in
       TAAJRODC41).   Note  that one  of  the attributes  describes the
       last  journal entry  sequence number  that was  processed.  This
       allows the function to restart properly when used again.

       The journal receiver of  the first journal entry  when STRAPYRMT
       was  used is  displayed.    This is  updated  when ENDAPYRMT  is
       used.

       Most  of the values in the APYRMTJRND  user space can be changed
       by the  Change  Apply Remote  Description  (CHGAPYRMTD)  command
       which prompts  with the current values.   Enter the  command and
       press Enter.

             CHGAPYRMTD

       Note that  changing some values such as  the journal name should
       only  be   done   if   you  have   significantly   changed   the
       environment.

  15.  The APYRMTJRN subsystem was  ended in a previous step  and is no
       longer  active.    If  you  want  to restart  the  function  for
       further  testing, enter (F9 must  be used with command prompting
       to access the TSTLIB parameter):

             STRAPYRMT    APYRMTLIB(APYRMTJRN) TSTLIB(TAATSTSIM)

       The  TSTLIB  parameter  describes  that  you  will  be  updating
       entries  into a test  library on  the local  system and  not the
       same library name on a remote system.

       You  may now try any additional  functions such as changing some
       of the  existing  objects  in  TAATSTLCL  and  checking  whether
       results were made to the corresponding object in TAATSTSIM.

       For example, you could do the following:

             CHGDTAARA     DTAARA(TAATSTLCL/DTAARAC) VALUE('ABC')
             SNDDTAQ       DTAQ(TAATSTLCL/DTQ2) ENTLEN(50)
                             ENTRY('APYRMTJRN test')
             DSPOBJD       OBJ(TAAJRODC4*) OBJTYPE(*PGM)
                             OUTPUT(*OUTFILE)
                             OUTFILE(TAATSTLCL/DSPOBJDP)
                             OUTMBR(*FIRST *ADD)

       You can add  a member to FILEA  (allows up 10 members)  and copy
       from  the first  member to  the new  member.   You can  update a
       record in a FILEA member by using EDTDBF such as:

             EDTDBF        FILE(TAATSTLCL/FILEA) MBR(xxx)


       You can check the results manually by using:

             DSPDTAARA     DTAARA(TAATSTSIM/DTAARAC)
             DSPDTAQ       DTAQ(TAATSTSIM/DTQ2)
             PRTDB2        FILE(TAATSTSIM/DSPOBJDP)

       Or you can check the results with the program:

             CALL          PGM(TAAJRODC43)

       You can add your  own objects to  TAATSTLCL and TAATSTSIM  (they
       must be  synchronized)  and then  use STRJRNPF  or STRJRNOBJ  to
       start journaling  to the objects in library  TAATSTLCL.  Specify
       the JRN1 journal in TAATSTLCL such as:

                STRJRNPF     FILE(xxx) JRN(TAATSTLCL/JRN1)
                STRJRNOBJ    OBJ(yyy) OBJTYPE(zzz) JRN(TAATSTLCL/JRN1)

       Then   make  any  changes  you  want  to  your  objects  in  the
       TAATSTLCL library.

       You can  review the  results manually or  use TAAJRODC43  again.
       The program  will compare  any data files,  data areas,  or data
       queues  found in  the TAATSTLCL  library with  the corresponding
       objects in TAATSTSIM.

       Two  other  test   programs  exist  that   may  be  used   after
       TAAJRODC41  to  allow   volume  testing.    The   first  program
       (TAAJRODC44)  allows you to  create up to  999 additional files.
       To create 100 files specify:

             CALL          PGM(TAAJRODC44) PARM('100')

       The files will be named TSTF001 - TSTF100.

       The second program  allows you  to write  n records  to each  of
       the files.

             CALL          PGM(TAAJRODC45) PARM('00200')

       200 records would be written to each of the TSTFn files.

       You may  use TAAJRODC45 at  any time  to add additional  records
       to  the TSTFn  files.  For  example, you  could run  the program
       before  and  after ENDAPYRMT.   TAAJRODC43  may  be used  at any
       time to compare the objects in the two libraries.

       If you are finished with the demonstration, end the function:

             ENDAPYRMT

  16.  If you have completed  the demonstration and want to  cleanup or
       repeat the  demonstration from the beginning,  a special program
       exists to delete the libraries.

             CALL      PGM(TAAJRODC49)

Demonstrating APYRMTJRN on both the local and remote systems
------------------------------------------------------------

This  demonstration requires  that you  be signed  onto both  the local
and remote  systems.   Be sure  to explicitly  follow the  instructions
about  whether  the  command  should  be run  on  the  'local'  or  the
'remote' system.

  1.   On both  systems, ensure the TAATOOL library  is on your library
       list by entering:

            EDTLIBL

       If the TAATOOL library does not exist, add it:

  2.   On the 'local'  system, ensure  the library  TAATSTRMT does  not
       exist by entering.

             DSPLIB      LIB(TAATSTRMT)

       If  the  library  exists,  it  is  probably  left  over  from  a
       previous  use  of  the   demonstration.    See  the  section  on
       'Cleaning  up  the local  and  remote system  demonstration' (it
       follows this  section) to  delete the  demonstration objects  on
       both  the 'local'  and 'remote'  systems.   Then  return to  the
       next step.

  3.   On  the 'local'  system,  create the  TAATSTRMT library  and the
       test objects.

             CALL        PGM(TAAJRODC81)

  4.   On the 'local'  system, display  the contents  of the  TAATSTRMT
       library.

             DSPLIB      LIB(TAATSTRMT)

       You should see:

           RCV0001      Journal receiver
           JRN1         Journal
           DTQ1         Data queue.  No entries exist.
           TSTFILE      Data Base file.  No records exist.
           DTAARA1      Data area.  Blanks exist.

       To  keep  the test  very  simple,  only  these objects  will  be
       replicated.     The   journal   and  journal   receiver  objects
       establish the  base required  by  the system  remote  journaling
       support.   The data  area, data  queue, and data  base file  are
       all journaled to JRN1 in TAATSTRMT.

       It is  important that the  journal be *USER  managed rather than
       *SYSTEM   managed.    When  the  system  manages  receivers,  it
       changes new  receivers  on an  IPL of  either  system and  often
       resets  the journal  sequence  numbers.   Changing receivers  is
       not  a problem when using APYRMTJRN,  but resetting the sequence
       numbers is.    All  journals  intended for  use  with  APYRMTJRN
       should be  MNGRCV(*USER).  A  later discussion describes  how to
       reset  the  sequence  numbers  (See  the  section on  'Resetting
       journal sequence numbers').

       Enter the command:

            CHGJRN    JRN(TAATSTRMT/JRN1) MNGRCV(*USER)

  5.   On the  'remote'  system,  ensure  library  APYRMTJRN  does  not
       exist by entering.

             DSPLIB      LIB(APYRMTJRN)

       If the library exists,  use DLTLIB (you may have  to respond 'I'
       to  ignore the message  that the  journal receiver has  not been
       saved).

  6.   On the 'remote' system, create the environment, with:

             CALL        PGM(TAAJRODC82)

       This  creates the TAATSTRMT  library (same name  as on the local
       system) and the objects that will be replicated.

  7.   On the 'remote'  system, display the  contents of the  TAATSTRMT
       library:

             DSPLIB      LIB(TAATSTRMT)

       You should see:

           DTQ1         Data queue.  No entries exist.
           TSTFILE      Data Base file.  No records exist.
           DTAARA1      Data area.  No value exists.

       The  objects  are  not journaled.    This  could  be done  to  a
       journal  on  the  remote  system,  but  is  not  needed for  the
       demonstration.

  8.   On the 'local' system,  to check the communication  environment,
       enter the command:

             WRKRDBDIRE

       You must  have an RDB  (Relational Data Base)  entry established
       to  the  'remote' system.   If  you  are not  familiar  with the
       communication requirements,  see  the  section  on  'Setting  up
       remote journaling communications'.

  9.   On  the 'local'  system,  use the  ADDRMTJRN  command to  add  a
       remote journal.   Use the  RDB name as  specified on WRKRDBDIRE.

             ADDRMTJRN     RDB(xxx) SRCJRN(TAATSTRMT/JRN1)
                             TGTJRN(*SRCJRN)
                             TEXT('Used by the TAA APYRMTJRN test')

  10.  On the 'remote' system, enter:

             DSPLIB        LIB(TAATSTRMT)

       You  should see  that the  system has  created the  JRN1 journal
       for you.

  11.  One of  the  critical requirements  to  make the  system  remote
       journaling function  successful is  to ensure that  the 'journal
       state'  of  the remote  journal is  *ACTIVE.   Although  you are
       checking the 'journal state' of  the 'remote' system, the  check
       must  be performed  on  the 'local'  system.    The TAA  command
       Check Remote Journal (CHKRMTJRN) can be used to check this.

       On the 'local' system, enter:

             CHKRMTJRN    SRCJRN(TAATSTRMT/JRN1)

       You  should  see the  TAA9895  escape message  stating  that the
       'journal state'  is *INACTIVE.   A  later section  will  discuss
       'Keeping the  remote journal  active'.   For the  demonstration,
       proceed to the next step.

  12.  On the 'local' system, to activate the journal, enter:

             WRKJRNA      JRN(TAATSTRMT/JRN1)

       Use  F16  (Work  with  remote  journal  information),  and  then
       Option  13 (activate).   Note that the  'journal state' does not
       change when Option  13 is used (you  must press F5 =  Refresh to
       see the new 'journal state').

  13.  On  the 'remote'  system,  to  see the  change  in the  library,
       enter:

             DSPLIB        LIB(TAATSTRMT)

       You  should see  that the system  has added  the RCV0001 journal
       receiver.   The  system  will  automatically  duplicate  entries
       from  the  'local'  journal  to   the  'remote'  journal.    The
       receiver used  on the 'remote' system is  like any other journal
       receiver.   You must  delete old  journal receivers  (after  the
       entries have been applied) based on a retention schedule.

  14.  On the 'remote' system, to see the journal entries, enter:

            DSPJRN         JRN(TAATSTRMT/JRN1)

       You should see the entries:

                  PR    Describes any previous journal receiver
                  JF    Starts journaling of a file
                  JM    Starts journaling of a member
                  EG    Starts journaling of a data area
                  QB    Starts journaling of a data queue

       These entries will  be ignored by  the apply program as  they do
       not change the data in an object.

       If  you display  the journal  on the  'local' system,  you would
       see the same entries.

  15.  On  the 'remote' system,  create the library  needed for the TAA
       APYRMTJRN function:

             CRTLIB        LIB(APYRMTJRN)
                             TEXT('Used by TAA APYRMTJRN tool')

  16.  On the 'remote'  system, create  a message queue  and set it  in
       *BREAK mode.

             CRTMSGQ       MSGQ(APYRMTJRN/TSTMSGQ)
                             TEXT('Used by TAA APYRMTJRN tool')

             CHGMSGQ       MSGQ(APYRMTJRN/TSTMSGQ) DLVRY(*BREAK)

       Placing  the message  queue in  break mode  is important  so you
       will  be quickly  informed  of any  errors or  important events.
       For the  demonstration,  the  message  queue is  placed  in  the
       APYRMTJRN  library.   This message  queue  will be  used on  the
       CRTAPYRMTD  command  instead  of the  default  name  of QSYSOPR.
       Any message queue and library could be used.

  17.  On the 'remote' system,  create the objects  needed for the  TAA
       APYRMTJRN function:

             CRTAPYRMTD    JRN(TAATSTRMT/JRN1)
                             MSGQ(APYRMTJRN/TSTMSGQ)

  18.  On  the   'remote'  system,   display  the   library  with   the
       controlling objects.  Enter:

             DSPLIB        LIB(APYRMTJRN)

       The APYRMTJRN  tool has its  own subsystem and job  queue.  User
       spaces   (*USRSPC  object  type)   are  used  for  communication
       between the APYRMTJRN  jobs and to  hold the definition  created
       by  CRTAPYRMTD.   The data  base  files are  used by  WRKAPYRMT.
       For  a  more  complete  description  of  the  objects,  see  the
       section on 'APYRMTJRN objects'.

  19.  On the 'remote'  system, start the  TAA APYRMTJRN function  with
       the command:

             STRAPYRMT

  20.  On the 'remote' system, display the active subsystems:

             WRKSBS

       Use Option  8 to display the  jobs for the  APYRMTJRN subsystem.
       You  should  see  the  batch  jobs  APYRMTJRN,  APYRMTJRN1,  and
       APYRMTJRNC.    See  the  section  on  'APYRMTJRN  Jobs'  for   a
       discussion of these jobs.

  21.  On the  'local' system,  call the  program to  add, update,  and
       delete records  in the file  TSTFILE, change the  data area, and
       send and receive entries from the data queue.

             CALL          PGM(TAAJRODC83)

  22.  On  the 'local'  system, review the  spooled output  of the data
       base changes in the spooled file TSTFILE:

             WRKSPLF

       The output describes  that 3 records  were added to the  TSTFILE
       data base  file.  Then one  of the records was  deleted, and one
       was updated.

  23.  Be  sure to  wait a few  seconds after  any change  to an object
       which is being  replicated before  displaying the  corresponding
       object  on  the  'remote'  system.     There  are  'wait'  times
       specified  in  the APYRMTJRN  function and  the  'remote' system
       needs some time to wake up and apply the entries.

  24.  On both the 'local' and  'remote' systems compare the data  base
       file using:

             PRTDB2       FILE(TAATSTRMT/TSTFILE)

  25.  On both the 'local'  and 'remote' systems compare the  data area
       using:

             DSPDTAARA    DTAARA(TAATSTRMT/DTAARA1)

  26.  On  both  the 'local'  and  'remote'  systems  compare the  data
       queue using:

             DSPDTAQ      DTAQ(TAATSTRMT/DTQ1)

       An  entry can be sent  to a data queue and  then received.  When
       a  'receive'  occurs, the  entry  is  removed.    Each  send  or
       receive  causes a journal  entry.   The apply  program processes
       both  the 'send' and  'receive' entries.  The  test program sent
       two data  queue  entries  and  then received  the  first  entry.
       Therefore, only the second entry still exists.

  27.  On the 'remote' system, to review the journal entries, enter:

            DSPJRN       JRN(TAATSTRMT/JRN1)

  28.  On  the   'remote'  system,  end   the  APYRMTJRN   function  by
       entering:

             ENDAPYRMT

       You  should see a break  message that the  APYRMTJRN function is
       ending.

  29.  On the 'remote' system, review the the spooled output with:

             WRKSPLF

       The  APYRMTJRN  spooled   file  describes  a   summary  of   the
       processing of  the APYRMTJRN job.   The APYRMTJRN1  spooled file
       is   optional   (see   CRTAPYRMTD  PRTAPYSTAT   parameter)   and
       describes the processing of the APYRMTJRN1 job.

  30.  The  objects that were changed by  journal entries are now known
       to the APYRMTJRN function  on the 'remote' system.   Each object
       has  caused  a record  to  be written  to  the  APYRMTP file  in
       APYRMTJRN.

       On the 'remote' system, review these records by entering:

            WRKAPYRMT

       The  next time APYRMTJRN is started  by STRAPYRMT, these records
       are used to create an  internal table which is searched using  a
       binary  search technique.    Any  journal activity  for  objects
       that  are not in  the internal table  are placed in  an overflow
       area and will be 'known' when APYRMTJRN is shutdown.

       Using WRKAPYRMT,  you can  change  which Batch  job is  used  to
       apply the entries  (up to 9 batch jobs  may be used) or  set the
       recovery  option  for  the  object  (see the  later  section  on
       'Resynching an object').

       Note  that any  changes made  using WRKAPYRMT  are not processed
       until  the  next time  the  APYRMTJRN  function  is  started  or
       refreshed.

  31.  For a  volume test,  do the following  on the 'local'  system to
       create the TSTAPYRMT file and start journaling.

             CALL      PGM(TAAJRODC46)

  32.  On the remote system, create the same file with:

             CALL      PGM(TAAJRODC47)

  33.  Use the TSTAPYRMT command with a few updates specified:

             TSTAPYRMT   NBRUPD(50)

       The  number of updates  also causes a percentage  of the updates
       to be  used for new  records and  the number  of deletions  that
       will  occur.   With NBRUPD(50),  30  records would  be added,  3
       deleted,  and  50  updates would  occur.    In  some cases,  the
       number you specify will be rounded up.

  34.  Start the apply function on the remote system.

                    STRAPYRMT

  35.  Wait a few seconds and then  check the number of records in  the
       file on both systems with:

            DSPMBRD    FILE(TAATSTRMT/TSTAPYRMT)

       Both files should have the same number of records (18).

  36.  End the test with:

           ENDAPYRMT

  37.  Start the apply remote process again with:

                    STRAPYRMT

       This  causes the  new  file  (TSTAPYRMT)  to be  placed  in  the
       internal array  which allows faster access  when journal entries
       occur.

  38.  Use TSTAPYRMT again and specify as large a number as desired:

             TSTAPYRMT   NBRUPD(nnnnn)

  39.  When  the records have been applied,  use DSPMBRD as previous to
       determine if the same number of records exist.

  40.  You can run as many  tests as required with TSTAPYRMT.   You can
       try  some of  the SNDAPYRMTE  options such  as  *SHUTDOWN, *CPY,
       etc.

  41.  You  can try  a  test where  the remote  system is  powered down
       before completing all  of the entries.   Specify TSTAPYRMT  with
       a large  value such  as NBRUPD(20000)  and then  power down  the
       remote system before it has applied all of the entries.

       When  you re-IPL, you  will need to  check to see  if the remote
       journal  is  still  active.    The  CHKRMTJRN  TAA  command   (a
       separate tool) provides a quick solution.  Enter:

            CHKRMTJRN    JRN(TAATSTRMT/JRN1)

       You should see that the remote journal is not active.

       The system command CHGRMTJRN  will allow you to set  the journal
       to an *ACTIVE state.  You must know the RDB value:

            CHGRMTJRN    RDB(xxx) JRN(TAATSTRMT/JRN1)
                           JRNSTATE(*ACTIVE)

       You can use CHKRMTJRN or WRKJRNA (F16) to check the status.

       To  apply  the entries  that  were in  process  when the  remote
       system  was powered  down, you must  use STRAPYRMT  again on the
       remote system.

       After the updates are  complete, you should see the  same number
       of records on the local and remote system.

  42.  When finished,  use ENDAPYRMT  to end the  apply and  review the
       spooled files that are output.

  43.  If   you  want   to  try  your   own  objects   using  the  same
       demonstration:

       On the 'remote' system, start the function with:

                    STRAPYRMT

         --   Create the same object in  library TAATSTRMT on both  the
              'local'  and 'remote'  systems.   The  objects should  be
              synchronized  (meaning  they have  the same  data)  as if
              you had used Save/Restore.

              On the 'local'  system, start journaling  to the  objects
              using STRJRNPF or STRJRNOBJ.   The journal to be  used is
              JRN1 in TAATSTRMT.

              On the 'local' system, change the objects.

              Depending on  the object type, changing the  data may not
              cause  a  journal  entry  to be  forced  to  the journal.
              Journal  entries are  often  buffered  so  that  multiple
              entries  can  be  written  at  one  time.    If  you  are
              experiencing  problems, use DSPJRN on  each system to see
              if   the   entries   exist.       See   the    SNDAPYRMTE
              OPTION(*FORCE) function to force the journal entries.

              Even  if  the  desired  journal  entries  exist  on  both
              systems,  be sure  to wait  a few  seconds for  the apply
              process  to  update  the  objects  before  checking   the
              results.

              Check the results with:

                   - PRTDB2 for data base objects
                   - DSPDTAARA for data areas
                   - DSPDTAQ for data queues

              If  you  want  to  simulate  error  conditions,  see  the
              section on 'Simulating an error condition'.

  44.  On the 'remote' system, to end the function, enter:

             ENDAPYRMT

       You  should see a  break message  describing that  the APYRMTJRN
       function has ended.

  45.  If  you no  longer need the  demonstration, proceed  to the next
       section.

Cleaning up the local and remote system demonstration
-----------------------------------------------------

  1.   On the 'local' system,  end the 'remote journaling'  function by
       entering:

            WRKJRNA        JRN(TAATSTRMT/JRN1)

       Use F16  (Work with remote  journal information), and  Option 14
       (Inactivate)  if the journal  state is *ACTIVE.   If you changed
       the journal  state, press  F5  to ensure  the journal  state  is
       *INACTIVE.

  2.   Use F3 to exit the WRKJRNA display.

  3.   On the 'local'  system remove the remote  journaling function by
       entering RMVRMTJRN.

            RMVRMTJRN      RDB(xxx) SRCJRN(TAATSTRMT/JRN1)

       If  you are not  familiar with the  RDB entry, use  WRKJRNA, F16
       (Work with  remote journaling  information), and  then option  5
       (Display remote journal details).   The RDB to use  is described
       as 'Relational database'.

  4.   On  the   'local'  system,  delete  the   TAATSTRMT  library  by
       entering:

            CALL           PGM(TAAJRODC89)

  5.   On   the  'remote'  system,  delete  the  TAATSTRMT  library  by
       entering:

            DLTLIB         LIB(TAATSTRMT)

       You may need to respond  'I' to ignore the inquiry  message that
       a journal receiver has not been saved.

  6.   On  the  'remote'  system,   delete  the  APYRMTJRN  library  by
       entering:

            DLTLIB         LIB(APYRMTJRN)

       If  the library  cannot be  successfully deleted,  recover based
       on the messages.

APYRMTJRN Overview
------------------

         Local System                           Remote System
         ------------                           -------------

     ************************               ************************
     *                      *               *                      *
     *   - Files            *               *   - Files            *
     *   - Data Areas       *               *   - Data Areas       *
     *   - Data Queues      *            -->*   - Data Queues      *
     *                      *           |   *                      *
     ************************           |   ************************
             |                          |
             |                          |
             |      **************      |                **************
             |      *            *      |                *            *
             |      * SNDAPYRMTE *      |                * APYRMTJRN  *
             |      *  command   *      |                *  objects   *
             |      *            *      |                *            *
             |      **************      |                **************
             |            |           *************        |
             v            |           *           *<--------
     ****************     |       --->* STRAPYRMT *         -----------
     *              *     |       |   *           * ------->|         |
     *    Journal   *<-----       |   *************         | Listing |
     *              *             |             |           |         |
     ****************             |             v           -----------
                                  |          ********
             |                    |          * MSGQ *
             |                    |          ********
             |                    __________________
             |                                     |
             v                                     |
     ****************                            ****************
     *              *                            *              *
     *   Journal    *             Some           *   Journal    *
     *  Receiver    *  ---->  Communication ---->*  Receiver    *
     *              *            function        *              *
     ****************                            ****************

Naming convention
-----------------

When you use the CRTAPYRMTD  command to create the required objects,  a
library must  be named.  The  name must be  9 characters or less.   The
default  is APYRMTJRN.   You  must first create  this library  with the
CRTLIB command.

The name of the  library is used  to name some  of the created  objects
and  jobs that  will  be  submitted.   For  example,  if you  took  the
default,  the subsystem  that  is created  is named  APYRMTJRN  and the
master job that is submitted is also named APYRMTJRN.

The  APYRMTJRN  tool may  be  used to  apply  the entries  for multiple
remote  journals on  the  same  remote  system.   However,  a  separate
CRTAPYRMTD command and library must be used for each journal.

While the  APYRMTJRN name  is the default,  you could name  the library
ABC.   You  must first  create  this library.   Using  the ABC  name on
CRTAPYRMTD would cause several objects  named ABC to be created in  the
ABC  library and  the ABC  'master' job  would be  submitted to  batch.
The  ABC  name   would  have  to  be  specified  on  commands  such  as
STRAPYRMT, WRKAPYRMT, etc.

The rest of the  documentation assumes that you  are using the  default
library name of APYRMTJRN.

APYRMTJRN Jobs
--------------

When  you enter  the  STRAPYRMT  command,  the APYRMTJRN  subsystem  is
started  and  the  APYRMTJRN  job  is  submitted  to  batch  using  the
APYRMTJRN job queue.

The  APYRMTJRN  job is  known as  the 'master'  job.   It  accesses the
objects  created by  CRTAPYRMTD  and  extracts  the  entries  from  the
remote journal  receiver.   Many journal code/type  entries (such  as a
save  of  an object)  are  ignored because  they are  not  required for
replicating data.  The  entries to be processed  (such as an update  to
a  data base  record) are  placed in  1-9 user  spaces (*USRSPC  object
type) that will be processed by 1-9 APYRMTJRNn apply jobs.

These  'apply' jobs are  submitted by the  APYRMTJRN job.   By default,
all entries  are applied  by the  APYRMTJRN1 job.   It  will always  be
submitted.  Using  the WRKAPYRMT command,  you can specify  which batch
job should  be used for any  object that is being  journaled.  Allowing
multiple  'apply' jobs allows  you to spread the  workload of the apply
function.  Using multiple  apply jobs should only be considered  if you
are not getting enough throughput from the default apply job.

Using  *USRSPC objects provides  the fastest  form of  asynchronous job
communication  between the apply jobs.  Pointers  are used to write and
read the data.

Another batch job APYRMTJRNC is also  submitted by STRAPYRMT.  It is  a
never ending job  that wakes up every  10 minutes.  The  intent of this
job  is to  ensure that  the other  batch  jobs are  still active.   If
WRKACTJOB is used, you will normally  see the APYRMTJRNC job as  active
with DLY-600.

When the APYRMTJRNC job wakes  up, it checks to see if  the other batch
jobs  are still  active.   If  not  active, a  message is  sent  to the
message  queue specified  on CRT/CHGAPYRMTD  if it  is in  *BREAK mode.
If not in *BREAK mode, a message is sent to QSYSOPR.

When ENDAPYRMT is used,  the APYRMTJRNC job is ended  immediately which
causes  an   abnormal  termination.    However,  the   message  to  the
submitter is suppressed and the job log is deleted automatically.

APYRMTJRN objects
-----------------

The  CRTAPYRMTD  command creates  several objects  in  a library.   The
default library is APYRMTJRN.

The following objects are created:

  **   APYRMTJRN *SBSD.  A subsystem  which is used for all batch  work
       required by  the tool.   The  maximum number of  jobs is  set to
       *NOMAX  and the  only pool  is  assigned to  *BASE.   A standard
       batch routing entry is  defined and a job  queue entry is  added
       for the APYRMTJRN job queue.

       If  you need  to  change the  attributes  of the  subsystem  use
       CHGSBSD and/or the TAA tool WRKSBSD2.

  **   APYRMTJRN *JOBQ.   A job queue which is  used for all batch work
       required  by  the  tool.   The  job  queue is  set  to  allow an
       unlimited number of batch  jobs to be run simultaneously.   This
       is important  as you  may have several  batch 'apply'  jobs that
       need to be activated from the job queue at the same time.

  **   APYRMTP  *FILE.    A  physical file  with  one  record  for each
       object  that  is   being  journaled.     The  file  is   updated
       automatically  when the  APYRMTJRN job  completes.   The  unique
       type/library/object/member   information  from   each  processed
       journal entry  is  used  to  create a  record.    The  WRKAPYRMT
       command can  be used to  review the objects  and change some  of
       the controlling entries for the objects being journaled.

  **   APYRMTL *FILE.  A logical over the APYRMTP file.

  **   APYRMTJRND  *USRSPC.    A  user  space  object  that  holds  the
       description  created by CRTAPYRMTD.   It also  contains the last
       journal  sequence  number  processed  to  allow   for  recovery.
       Other  commands such as  CHGAPYRMTD, DSPAPYRMTD,  and RTVAPYRMTD
       also operate on the description.

  **   APYRMTJRNE  *USRSPC.  A  user space object that  holds any error
       information that  is  passed between  the APYRMTJRN  master  job
       and  the  APYRMTJRNn  apply  jobs.   The  apply  jobs  post  the
       information and  the master job extracts it  and then blanks out
       the user space.   You  would normally  see blanks  in this  user
       space.

  **   APYRMTJRN1  *USRSPC.    A  user  space  object  that  holds  the
       entries that are  to be applied by the  APYRMTJRN1 job.  This is
       a  large user space (16MB) providing  for multiple entries to be
       written.   The entries  are  written from  the APYRMTJRN  master
       job and read  by the APYRMTJRN1 apply job.   The user space also
       contains  the next  location that a  entry should  be written to
       by APYRMTJRN and the next  location an entry has been  processed
       from by the APYRMTJRN1 job.

  **   APYRMTJRN2-9 *USRSPC.   User space objects that  will be created
       by APYRMTJRN  if additional batch jobs are  required.  These are
       also 16MB in size.  The  spaces are only created if you  specify
       that additional batch jobs are needed using WRKAPYRMT.

       If you  specify an additional  batch job and  then change to  an
       existing batch  job so the  user space is no  longer needed, the
       user  space will remain.   You may  cleanup with DLTUSRSPC after
       ending the function with ENDAPYRMT.

Commands provided
-----------------

Commands that work with  the description of the APYRMTJRN  function all
run on the 'remote' system.

   CRTAPYRMTD    Creates   the  objects   required  by   the  APYRMTJRN
                 function.   The attributes  defined are  placed in the
                 APYRMTJRN  user  space.    For  each  journal   to  be
                 processed, a  separate CRTAPYRMTD command  is required
                 with a separate library.

   CHGAPYRMTD    Changes  the description of  the APYRMTJRN attributes.
                 The command  can  only  be  used  interactively.    It
                 extracts the current  values from the  APYRMTJRND user
                 space and  uses the CHGAPYRMT2 command  to prompt with
                 the current values.

                 This  approach is used  to avoid the  restriction of a
                 prompt override  program attempting  to access a  user
                 space  and  running  into  a QALWUSRDMN  system  value
                 restriction.

   CHGAPYRMT2    Changes  the description of  the APYRMTJRN attributes.
                 The command  may be  used interactively  or in  batch.
                 All parameters prompt with *SAME.

   DSPAPYRMTD    Displays the  attributes of the APYRMTJRN  user space.

   DLTAPYRMTD    Deletes   the  objects   created  by   the  CRTAPYRMTD
                 command.

   RTVAPYRMTD    Retrieves the attributes  of a APYRMTJRN  description.

   WRKAPYRMT     Provides  a  work  display of  the  objects  that  are
                 known  by the  APYRMTJRN  function.   The  records are
                 stored  in the  APYRMTP data base  file.   The file is
                 updated  each  time  the  APYRMTJRN  job  ends   or  a
                 refresh occurs  (see SNDAPYRMTE).  You  may change the
                 controlling   attributes   for   the   objects   being
                 journaled,  but  the  change  will  not  be  processed
                 until the  APYRMTJRN function  is ended  or refreshed.
                 The  WRKAPYRMT   delete  option  described  the  wrong
                 error  if   the  object   exists.     This  has   been
                 corrected.

Run time commands

   STRAPYRMT     Runs on  the 'remote'  system to  start the  APYRMTJRN
                 subsystem  and   submits  the  APYRMTJRN   job.    The
                 APYRMTJRN   job  will  submit  1-9  apply  jobs  named
                 APYRMTJRNn  depending on  which  batch jobs  (if  any)
                 you have specified to process the entries.

   ENDAPYRMT     Runs   on  the   'remote'  system   to  shutdown   the
                 APYRMTJRN function.

   SNDAPYRMTE    Runs  on  the  'local' system.    It  sends  a special
                 journal entry (various  options) to  the journal  that
                 is being processed  on the 'remote' system.   The type
                 of  journal entry  requested causes functions  such as
                 'shutdown'.

   CHKACTJRN     The separate  tool  runs  on  the  'local'  system  to
                 check if the remote journal is still active.

Security considerations
-----------------------

Security  is   controlled  by  an   authorization  list,  the   use  of
individual authorizations, and the program adopt function.

  **   An  authorization list (TAAAPYRMT)  is shipped with  the product
       that  controls the  most sensitive commands.   The authorization
       list is shipped so that the *PUBLIC user is *EXCLUDE.

       You must be authorized to TAAAPYRMT to do the following:

              CRTAPYRMTD
              STRAPYRMT
              ENDAPYRMT
              SNDAPYRMTE

       The following commands are public:

              CHGAPYRMTD  - requires *CHANGE auth to a *USRSPC
              CHGAPYRMT2  - requires *CHANGE auth to a *USRSPC
              DLTAPYRMTD  - requires *ALL authority to objects
              DSPAPYRMTD  - requires *USE auth to a *USRSPC
              RTVAPYRMTD  - requires *USE auth to a *USRSPC
              WRKAPYRMT   - requires *CHANGE auth to a *USRSPC

  **   The STRAPYRMT  programs,  all  use the  program  adopt  function
       USRPRF(*OWNER)  to adopt  the  authority of  the QSECOFR  owner.
       This  allows  complete  access  and  update  capability  to  any
       object  while the  function  is  running.    The  ENDAPYRMT  and
       SNDAPYRMTE commands also adopt.

       A  system   operator  who   is  authorized   to  the   TAAAPYRMT
       authorization  list  may  start  and  end  the function  without
       specific authorization to any of the objects.

  **   The  subsystem  that  is  created   by  CRTAPYRMTD  is  set   to
       AUT(*USE) so that  only the user  who did CRTAPYRMTD  may change
       it.

  **   The  job   queue  associated  with  the  subsystem   is  set  to
       AUT(*EXCLUDE).   This  prevents a  user from  submitting work to
       this job queue  which allows an unlimited  number of jobs to  be
       active.

  **   The  CRTAPYRMTD AUT  parameter determines  the authority  to the
       APYRMTP  file.  The  default is *USE.   The  owner may authorize
       other users to update the file.

The user spaces  that are created are  set to AUT(*USE).   A user  must
have *CHANGE authority to change the data.

APYRMTJRN Processing
--------------------

When  the  STRAPYRMT command  is  entered  on  the 'remote'  system,  a
library  is named.  A  subsystem with the  same name as  the library is
started.   Assuming  the  library  name  is  APYRMTJRN,  the  APYRMTJRN
subsystem would  be started and  the APYRMTJRN  job would be  submitted
to the APYRMTJRN job queue.

The  APYRMTJRN job  first checks  to see  if  the APYRMTJRNn  jobs have
completed  normally.   If not,  these jobs  are started with  a special
value that tells them to  end when they are caught up  applying journal
entries.   This  means no  new journal  entries are  applied  until the
entries  that were processed by the  prior APYRMTJRN job are completed.

The APYRMTJRN job then reads  the APYRMTP file which contains a  record
for  each object  that has  had  journal activity  since APYRMTJRN  was
first  used for  the  specified journal.   On  the initial  use  of the
command, no objects are known.

A table  is setup  within the  program with  an entry  for each  object
(type/object/library/member) and an 'existence test' is made.

The attributes of the  object are retrieved such as  the maximum record
length  for  a data  base  file, the  length  of a  data  area, or  the
maximum  entry length  of a  data queue.   This information  is updated
into  the table  and  is  used when  checking  a  journal entry  to  be
processed.

Data base  entries are  rejected if the  record length does  not match.
This  helps  ensure that  consistent object  definitions  exist between
both the local and remote systems.

Data Area  and Data  Queue length  checking is  not as  strict as  Data
Base  checking.   Data  Area  and Data  Queue  journal  entries do  not
describe  the maximum  length of the  object, but  only of  the change.
If the change  length is less than  or equal to  the the remote  system
maximum  length,  the  entry  will be  applied.    The  entry  will  be
rejected  if  it is  larger  than  the maximum  allowed  length on  the
remote system.

Since  on  the initial  use  of the  STRAPYRMT  command no  objects are
known, all table entries are  marked to be processed by  the APYRMTJRN1
job.  This job is always submitted to batch.

The  journal receiver  is  read by  the QjoRetrieveJournalEntries  API.
Each  journal entry contains  the journal code and  type, the qualified
object name, the member,  and relative record number  (if it is a  data
base  record entry)  as well  as the  data  (such as  the record  image
after an update).

Only those  journal codes and types that impact  data (such as a record
update or a  data area  change) are  processed.   Special entries  from
the SNDAPYRMTE  command are also  processed (see  the section on  'Send
Apply Remote Entry').

When a journal  code/type is to be processed,  the object name from the
journal  entry is  used in a  lookup (binary search)  against the table
that was built  at the beginning  of the program.   If the  table entry
is not  found, an overflow  area (another internal table)  is searched.
If  the entry still does not  exist, it is added  to the overflow area.

The journal entries to be processed  are placed in a unique user  space
for  each   batch  apply  job.     These  user  spaces   (APYRMTJRN1  -
APYRMTJRN9)  are  automatically created  in  the  library specified  by
CRTAPYRMTD  if  the  corresponding  batch  job  is  needed.    Multiple
entries  are   placed  in  the   user  spaces  to   allow  asynchronous
processing  between  the  master job  (APYRMTJRN)  and  the apply  jobs
(APYRMTJRN1 - APYRMTJRN9).

When  there are  no more  journal entries  to be processed,  the master
job goes  into a  wait.   An  option on  CRT/CHGAPYRMTD determines  how
long a  wait occurs.   When the  master job wakes  up after a  wait, it
uses the API again to see if new entries exist.

The  apply job  accesses the  user space  and compares  the information
posted by the  master job describing  the next location  to be  written
versus the  information posted by the  apply job for the  next location
to  be processed.   If they  are the  same, the  apply job goes  into a
wait.  An option on CRT/CHGAPYRMTD  determines how long a wait  occurs.
When  the locations  differ,  a  journal  entry is  processed  (special
handling occurs when the user space is filled to its 16MB limit).

When the  first journal entry occurs  to change the data  contents of a
record  for  a  specific member,  the  member  is opened.    The member
remains open for the duration  of the APYRMTJRN job (unless ended  by a
SNDAPYRMTE option).   If  the member is  open, you cannot  allocate it,
change the description of the member, initialize the member, etc.

The following data base entries are processed:

  **   Add.   Does  a 'write'  to  the file.   It  is possible  that an
       error such  as a  'duplicate  key' would  occur and  the  record
       would not  be added.   After  a successful  write, the  relative
       record  number  of  the  inserted  record  is  compared  to  the
       relative record number in  the journal entry.   An error  occurs
       if the numbers differ.

  **   Update.  Does a  chain by relative record number  and an update.
       An  error  is posted  if  the relative  record  number does  not
       exist.  Other errors are possible such as a 'duplicate key'.

  **   Delete.   Does a  chain by relative record  number and a delete.
       An error  is  posted  if the  relative  record number  does  not
       exist.

Special handling  occurs for PX journal  types which cause  an 'add' to
a  specific relative record number.   A PX  entry typically occurs when
an 'add' is used in a 'reuse deleted records' type of file.

The  CRTJRN  MINENTDTA  function  is  supported.    This  provides  for
shorter journal  entries when  an update  occurs.   Additions are  full
length.   Record length  checking does not  occur if the  journal entry
is minimized.

Some member level  changes such  as INZPFM, ADDPFM,  CLRPFM, RMVM,  and
RNMM  are  also  handled.    See  the  later  sections  on  RGZPFM  and
MOVOBJ/RNMOBJ.

Data area  changes for either the  full length or a  partial length are
processed.  Both character and decimal data areas can be changed.

Data  Queue  changes  either keyed  or  non-keyed and  with  or without
'sender ID'  are handled.   The specific  entry caused  by the  CLRDTAQ
API is also  handled.  If the QRCVDTAQ program is  called to receive an
entry  on the  local system and  no entry  exists, no  journal entry is
generated.  If a 'receive' request  occurs on the remote system and  no
entry exists, no error occurs.

For  data base  files,  the  apply programs  use  C  language run  time
library  functions  to perform  I/O.   The  first journal  entry  for a
library/file/member establishes a  pointer to the  object that is  used
if additional  journal entries occur  for the same  member.  The  files
remain  open to  improve performance.   Closing the  file on  the local
system  does not  cause the  file on  the remote  system to  be closed.
Leaving the  files open  prevents the use  of certain  commands on  the
'remote' system.   You can close a file/member on  the remote system by
using  a  SNDAPYRMTE option  on  the 'local'  system.   Ending  the job
closes all of the data base files.

Note that  the APYRMTJRN  jobs are  written so  that  they will  remain
active waiting  for more entries  to be placed  into the journal  or to
be applied.

All  APYRMTJRN jobs  listen for  an ENDJOB  command by  use of  the RPG
SHTDN operation code.   A 'shutdown' could be  caused by the  ENDAPYRMT
command which allows  you to terminate  the subsystem gracefully.   You
may also  end the subsystem by  using a SNDAPYRMTE option  on the local
system.

When  the APYRMTJRN job is ended,  the entries from the internal tables
are written  to the APYRMTP  file.   The next  time STRAPYRMT is  used,
the information  in the file is placed  in the main table.   Once there
are  object records  in  the APYRMTP  file, you  may use  the WRKAPYRMT
command to specify options  on the object being  applied to.   Changing
an option  will not  impact the  APYRMTJRN function  if it is  running.
However,  at the  next refresh  or  next use  of STRAPYRMT,  the option
will be used.

Note that once  the object  is known  (at least one  journal entry  has
caused data  to be changed), a  record of the  object is placed  in the
file and  table.  If no  additional activity to the  object occurs, the
file  and  table  entry  will still  exist  (this  causes  only minimal
overhead as  files are  not opened  unless  activity occurs).   If  the
object is  no longer part of  the application, use  WRKAPYRMT to remove
the record from the file.

Each  time the APYRMTJRN job is ended,  a listing of the internal table
is made.  A  line is printed for each  known object containing a  count
of  journal  activity  and  any errors  that  have  occurred  (see  the
section on 'Error Handling').

An option  exists (on CRT/CHGAPYRMTD) to have  a summary listing of the
activity for each apply job.

SNDAPYRMTE Command (Send Apply Remote Entry)
--------------------------------------------

The SNDAPYRMTE command  is used on  the local system  to cause  actions
to  the APYRMTJRN  job  that is  running  on the  remote  system.   For
example,  a  method of  ending  the remote  system  APYRMTJRN jobs  and
subsystem is to specify:

             SNDAPYRMTE   JRN(xxx) OPTION(*SHUTDOWN)

Note  there is no 'startup' function  supplied by the APYRMTJRN tool to
run from the local  system.  The STRAPYRMT  command must be run  on the
remote system.  SBMRMTCMD could be used to submit the command.

In addition to 'shutdown', you may specify an option to"

      - Initialize the activity statistics
      - Print the table without ending the APYRMTJRN function
      - Refresh the table
      - End an object (stop applying changes)
      - Start an object (allow journal entries to be applied)
      - Copy an object (refresh the data)
      - Check the time it takes to process an entry
      - Force entries from the local system buffer to the journal

All SNDAPYRMTE journal  entries that are sent to  the remote system are
forced to the journal.

See the SNDAPYRMTE command for specific details about each option.

Commitment Control processing
-----------------------------

When  commitment control is used,  the journal code 'C'  is used by the
system for special journal  entries.  You can  review what the  journal
entries  look  like by  using  DSPJRN  during  the demonstration  on  a
'single system'.   Commitment control was used  for FILEB in TAATSTLCL.

When a 'commit  cycle' begins,  the SC  type journal  entry is  written
for a  'start of commit'.   In a normal  commit operation, the  SC type
would  be  followed by  journal  entry 'R'  codes  (record change)  for
updates  (both before  and after  images), puts  (writes), and deletes.
If  the program  issues  a  'commit',  the CM  type  journal  entry  is
written to say the commit group is complete.

If  a rollback  occurs, the  system sends  special entries  such  as DR
(record  deleted for rollback),  BR (update  before-image for rollback)
to reset  the data base,  followed by  an RB  entry to  say a  rollback
occurred.  The RB entry ends the 'commit cycle'.

If  there is  no interruption  in the  entries as  they are  processed,
APYRMTJRN handles  both a successful commit  and a successful rollback.

If however,  processing  is  interrupted before  the  commit  cycle  is
completed by  either a  CM or RB  entry occurs,  some entries  would be
applied  to the 'remote'  system without  establishing a  proper commit
boundary.

In  the case  where the communication  line fails,  the commit boundary
would  be  correct once  the  communication  line  is  brought  up  and
APYRMTJRN begins processing the missing entries.

Error handling
--------------

If errors are  detected during processing, the object  is flagged as in
error  and  a  message  is  sent  to  the  message  queue specified  on
CRT/CHGAPYRMTD.  Typical errors include:

  **   An object does not exist to apply an entry to.

  **   The length of the journal  entry does not agree with the  remote
       file definition.   For example,  you have added  a new  field to
       the  local file and have  forgotten to change  the definition on
       the remote system.

  **   The relative record number  of an add of  a new record does  not
       agree between the local and remote systems.

  **   A duplicate key error has occurred.

Errors are  handled  differently depending  on the  'Recovery type'  as
specified using WRKAPYRMT (default is S/R').

   S/R           For the  first error detected on an  object, a message
                 is   sent   to   the   message   queue   specified  on
                 CRT/CHGAPYRMTD.   Once  an object  is marked  with  an
                 'error  indication',  all subsequent  journal  entries
                 for  the   same  object  are  bypassed.    The  normal
                 recovery method would  be either  Save/Restore or  the
                 SNDAPYRMTE OPTION(*CPY) function.

                 If the  APYRMTJRN function is shutdown  and restarted,
                 the  'error indication' will  no longer  exist and the
                 journal entries will be attempted  to be applied.   If
                 the object is  still in error, the  'error indication'
                 will be set again.

                 The 'error  indication' is reset by  the journal entry
                 caused  by  INZPFM or  the  QCLRDTAQ API  (the  API is
                 called  by  the TAA  CLRDTAQ  command).    The  'error
                 indication'   is   also   reset  by   the   SNDAPYRMTE
                 OPTION(*CPY) function.

   *EDT          For  serious  errors  (such  as  the  object does  not
                 exist, wrong  length,  etc),  the  processing  is  the
                 same as *S/R.

                 For  minor errors  (such  as  a mismatch  in  Relative
                 Record  numbers  on  an  add),  each  error  causes  a
                 message to be sent to  the message queue specified  on
                 CRT/CHGAPYRMTD.    Processing  of  additional  journal
                 entries  to  the same  object  continues.   Additional
                 errors may occur.

                 The  use of  *EDT is intended  for the  case where the
                 object  is   too  large   to  consider   the  use   of
                 Save/Restore  (except when  serious errors  occur) and
                 some  form of user  editing will be used  to bring the
                 files into synch.

The listing which occurs  at the end of  the program (or by  SNDAPYRMTE
OPTION(*PRINT))  will include  a flag  for  those objects  that do  not
exist  and  those that  have had  journal  activity that  could  not be
processed.

If the  object is  marked  as in  error, you  must  get the  local  and
remote  versions  of  the object  in  synch  before  APYRMTJRN  can  be
effective.

Once  you  have the  objects  in  synch between  the  local and  remote
systems, do either:

  **   If    the   APYRMTJRN    job   is    running,   use   SNDAPYRMTE
       OPTION(*STROBJ) to  tell  the APYRMTJRN  job  to start  applying
       entries to the object.

  **   If the  APYRMTJRN job is  not running, the journal  entries will
       be  applied  normally  the  next  time  you  run  the  STRAPYRMT
       command.

Simulating an error condition
-----------------------------

To see  how APYRMTJRN  handles errors,  the following  assumes you  are
using the demonstration for both the 'local' and 'remote' systems.

  **   On the 'remote' system, display the description:

             DSPAPYRMTD

Ensure that the message queue described is in break mode.

  **   To simulate a relative record error, you could:

       On the 'remote' system, create a file:

             CRTPF         FILE(TAATSTRMT/FILEX) RCDLEN(50)

       On the 'local' system, create the same file:

             CRTPF         FILE(TAATSTRMT/FILEX) RCDLEN(50)

       On the 'local' system, enter a single record by using:

             EDTDBF        FILE(TAATSTRMT/FILEX)

       When  the initial  prompt appears,  you  will be  in 'add  mode'
       because  there are  no records in  the file.   Enter  one record
       with a value such as 'RECORD 1' and then end EDTDBF.

       On the 'local' system, start journaling with:

             STRJRNPF      FILE(TAATSTRMT/FILEX)
                             JRN(TAATSTRMT/JRN1)

       On the 'local' system, use EDTDBF again:

             EDTDBF        FILE(TAATSTRMT/FILEX)

       When the  initial  prompt  appears,  you  will  be  in  'display
       mode'.   Press F9 to  enter 'add mode'.   Enter a  second record
       with a value such as 'RECORD 2' and then end EDTDBF.

       When the  apply program attempts to add a  record, there will be
       a  mismatch in the  relative record numbers  because the 'local'
       system has done an add at  RR # 2 while the 'remote'  system has
       done an add  at RR # 1.   You should see a  break message occur.

       On the 'remote' system, display the records in the file using:

             PRTDB2        FILE(TAATSTRMT/FILEX)

       Note  that the record in  error was actually  added to the file.
       In  the case  of  an  'add'  it  cannot  be  determined  that  a
       mismatch occurs until the record is added.

  **   To simulate a record length error, you could:

       On the 'local' system, create a file:

             CRTPF         FILE(TAATSTRMT/FILEY) RCDLEN(50)

       On the  'remote' system, create the  same file with  a different
       record length:

             CRTPF         FILE(TAATSTRMT/FILEY) RCDLEN(45)

       On the 'local' system, start journaling with:

             STRJRNPF      FILE(TAATSTRMT/FILEY)
                             JRN(TAATSTRMT/JRN1)

       On the 'local' system, use EDTDBF and enter a single record:

             EDTDBF        FILE(TAATSTRMT/FILEX)

       The  apply program will  sense a  mismatch in the  record length
       of the  journal data  and the  file.   You  should see  a  break
       message appear.

  **   To simulate a missing object:

       On the 'local' system, create a data area:

             CRTDTAARA     DTAARA(TAATSTRMT/DTAARA1) TYPE(*CHAR)
                             LEN(10)

       On the 'local' system, start journaling with:

             STRJRNOBJ     OBJ(TAATSTRMT/DTAARA1) OBJTYPE(*DTAARA)
                             JRN(TAATSTRMT/JRN1)

       On the 'local' system, change the data area

             CHGDTAARA     OBJ(TAATSTRMT/DTAARA1) VALUE('ABC')

       The apply  program will sense  that the  object does not  exist.
       You should see a break message appear.

Managing the APYRMTJRN function
-------------------------------

There are several functions that need to be considered:

  **   Any journals  to be handled must be  MNGRCV(*USER).  Use WRKJRNA
       to  check for the  setting and if needed,  use CHGJRN to specify
       MNGRCV(*USER).

  **   The 'journal state'  must be kept *ACTIVE.   See the section  on
       'Keeping the remote journal active'.

  **   The  APYRMTJRN function  must be  started on  the  remote system
       after  each IPL  with the STRAPYRMT  command.   Consider an auto
       start job.

  **   You should keep  the message  queue specified on  CRT/CHGAPYRMTD
       in  break mode.    This will  quickly inform  you  of errors  or
       significant  events.  If you  choose a message  queue other than
       QSYSOPR, consider who will manage this queue.

  **   Review the  listing produced  when the  APYRMTJRN job  completes
       (or by use  of SNDAPYRMTE OPTION(*PRINT)).   This will  list all
       of  the objects that  are known  (have had any  journal activity
       in  the current or prior use  of APYRMTJRN), whether they exist,
       and whether errors have occurred during processing.

       You should ensure that no errors were found.

  **   Determine  when  to  change  journal  receivers  on   the  local
       system.   This will automatically  create a new receiver  on the
       remote system.

       Delete  old  receivers  on both  the  local  and  remote system.
       Keep the previous version online  until another new receiver  is
       added.

       Consider the use of the TAA MTNJRN command for both systems.

  **   Resynch objects when  required (see the section  on 'Re-synching
       an object'.

  **   The  number of  journal sequence numbers  that may  be processed
       by APYRMTJRN  is  10  billion  (9,999,999,999).    Messages  are
       provided  at various  points when  the  sequence number  exceeds
       9,000,000,000.    See  the  section  on 'Resetting  the  journal
       sequence numbers'.

       Note  that though journal  sequence numbers may  be supported by
       the system to a  number considerably larger than 9  billion, the
       APYRMTJRN tool restricts to 10 digits.

Resetting the journal sequence numbers
--------------------------------------

Because  the   APYRMTJRN  tool  is  dependent   on  ascending  sequence
numbers,  it is  important that when  the journal  sequence numbers are
to be reset, that you perform the following steps.

  **   On the 'remote' system, end the APYRMTJRN function:

            ENDAPYRMT

  **   On the 'local'  system use CHGJRN  to change to  a new  receiver
       and reset the sequence numbers.

            CHGJRN     JRN(xxx/yyy) JRNRCV(*GEN) SEQOPT(*RESET)

  **   On the 'local' system, do WRKJRNA:

            WRKJRNA    JRN(xxx/yyy)

       Use F15 to display the journal receivers.

       Delete all but the currently attached journal.

       Note the  name of the  journal receiver and  library to  be used
       later.

  **   On the 'remote' system, do WRKJRNA:

            WRKJRNA    JRN(xxx/yyy)

       Use F15 to display the journal receivers.

       Delete all but the currently attached journal.

  **   On the 'local' system, do DSPJRN:

            WRKJRNA    JRN(xxx/yyy)

       Ensure that the beginning journal sequence number is '1'.

  **   Start  the  APYRMTJRN  job  on  the  'remote'  system  with  the
       sequence number and new receiver name and library:

            STRAPYRMT   LIB(lll) JRNRCV(xxx/yyy) SEQNBR(1)

       The new  receiver  should then  be  processed beginning  at  the
       first sequence number.

Referential Integrity and Triggers
----------------------------------

Both  Referential Integrity  constraints and  Trigger  programs on  the
local system  may cause an action  against a data base file  such as an
add  or a delete.   If the  file being changed  is journaled, a journal
entry would be passed to the remote system.

If  the system  APYJRNCHG  command  is  used, the  system  applies  the
entries  and  does not  invoke  the  Referential  Integrity or  trigger
function.    However,  since  the  APYRMTJRN  tool  is  an  application
program, the  same Referential  Integrity or  Trigger  function on  the
remote system could  cause the original action to be  duplicated.  This
could result in a mismatch of relative record numbers.

An  option  exists  on  CRT/CHGAPYRMTD  for  the  handling  of  journal
entries caused  by  Referential  Integrity  constraints  and  triggers.
See the APYREFITG and APYTRIGGER parameters.

The  default is  *NO meaning  that  the entries  are  bypassed and  not
applied  on  the  remote system.    The  default  does  not impact  the
original  file.   For example,  if FILEA  is changed by  an application
and a  trigger program for  FILEA causes a  new record  to be added  to
FILEB,  it is  the FILEB  journal entry  that is  bypassed.   The FILEA
journal entry would be applied normally.

If  your intent in  using the APYRMTJRN  tool is  for high availability
(the ability  to switch  operations to  the remote  system), you  would
want  the  same  Referential  Integrity and  trigger  functions  to  be
active on  the remote system.  You should take  the default of *NO.  In
the FILEA/FILEB  example,  the trigger  program  on the  remote  system
would generate the new record for FILEB.

If your intent in using  the APYRMTJRN tool is for backup  of data (you
have not  duplicated the program environment), you  should specify *YES
to have the entries applied.

RGZPFM
------

Because  the  APYRMTJRNn  jobs  are  processing  journal  entries  in a
single job, any RGZPFM requests  would hold up processing of  any other
journal  entries  for  the  apply  job  until  the  reorganization  was
complete.

For   this  reason,  a  RGZPFM  journal   entry  is  bypassed  and  the
file/member  is  marked  as  in  error.    No  other  entries  will  be
processed until  the files are re-synchronized.   A message is  sent to
the specified message queue if a RGZPFM journal entry is found.

You  can re-synchronize  using Save/Restore  and then  begin processing
again by using SNDAPYRMTE OPTION(*STROBJ).

An alternative  to RGZPFM  is to  use the  TAA tools  Compress  Deleted
Records (CPRDLTRCD)  and Truncate Deleted  Records (TRNDLTRCD).   These
tools  allow you  to reclaim  deleted record  space  with only  a brief
period where the file is unusable by other jobs.

See the section on 'Significant object changes'.

MOVOBJ/RNMOBJ
-------------

APYRMTJRN  assumes  a  static  environment.   Any  journal  entries for
MOVOBJ or RNMOBJ are flagged and the object is marked in error.

See the section on 'Significant object changes'.

Significant object changes
--------------------------

The following describes some typical situations and solutions:

  **   Data Base  record format change  is required  (such as adding  a
       new field, changing a definition, etc).

       Quiesce  the application  on  the local  system  to prevent  any
       changes  to  the data.    Use STRAPYRMT  OPTION(*ENDOBJ)  to end
       applying changes to the remote  system.  Make the change on  the
       local  system.    Use  a  Save/Restore  approach  or  SNDAPYRMTE
       OPTION(*CPY)  as  described in  the section  on  'Re-synching an
       object'.

  **   RNMOBJ or MOVOBJ is required.

       Quiesce the  application on  the local  system.   Use  STRAPYRMT
       OPTION(*ENDOBJ) to  end applying changes  to the  remote system.

       Rename or move the object on both local and remote systems.

       Note there  is no need to describe the  new object on the remote
       system  to  APYRMTJRN.   It will  recognize journal  entries for
       the newly  named object  and begin  applying changes.   You  may
       want  to  delete  the old  name  from  the  data base  with  the
       WRKAPYRMT command to avoid clutter.

  **   RGZPFM  is  required  (see  the  TAA  Compress  Deleted  Records
       (CPRDLTRCD) tool  for  an alternative  solution).   Because  the
       relative record numbers  will be reset, CPRDLTRCD  should not be
       used  in  certain applications  that  utilize  existing relative
       record numbers.

       Quiesce the application on the  local system and use  SNDAPYRMTE
       OPTION(*ENDOBJ) to  prevent applying any  changes on  the remote
       system.  Use RGZPFM on the local system.

       Use  either RGZPFM on  the remote  system or use  a Save/Restore
       approach   or  SNDAPYRMTE  OPTION(*CPY)   as  described  in  the
       section on 'Re-synching an object'.

Re-synching an object
---------------------

There will be  instances when an  object needs to  be re-synched.   You
must describe to APYRMTJRN which technique you will be using.

  **   The  default resynch  method  defined for  WRKAPYRMT is  '*S/R'.
       This   means  you  will  use   the  Save/Restore  or  SNDAPYRMTE
       OPTION(*CPY) technique to resynch an object.

  **   The  option  for  WRKAPYRMT  is  '*EDT'  which  means  you  will
       provide a manual resynch.

The following describes these approaches:

  **   Save/Restore.    You  would  quiesce the  object  on  the  local
       system,  and  use SNDAPYRMTE  OPTION(*ENDOBJ)  to  stop applying
       changes.  Save  the object on  the local system  and restore  it
       to the  remote system.   If the  APYRMTJRN function is  running,
       use  SNDAPYRMTE OPTION(*STROBJ)  to  reset the  object  to allow
       journal  changes  to  occur.    If  APYRMTJRN  is  shutdown, the
       startup function will accomplish the same thing.

  **   SNDAPYRMTE OPTION(*CPY).  This  function will refresh an  object
       by copying  the data  to itself.   An exclusive lock  (*EXCL) is
       required.   The  object and data  are duplicated  to the TAAWORK
       library, the object  is cleared, and then  data is copied  back.
       The 'clear'  and 'copy  back' cause journal  entries to  flow to
       the  remote  system.   The  'clear' function  causes  the 'error
       indication'  to  be  reset  so  that  journal  entries  will  be
       applied.      There    is   no   requirement    for   SNDAPYRMTE
       OPTION(*ENDOBJ) or OPTION(*STROBJ).

       Note  that for  data  base  files, the  relative  record numbers
       will  be changed if deleted records  exist in the original file.
       You should  not use this  function if you  are dependent on  the
       original relative record numbers in the file.

  **   Manual  correction.  The  typical solution  would be  to correct
       the  data  that is  in  error with  a function  such  as EDTDBF,
       CHGDTAARA, etc.  See the  discussion on 'Comparing objects  from
       different systems' for different solutions.

Performance
-----------

There  are several  major factors  that influence  performance.   There
are also functions you can used to tailor the performance.

  **   The number  of journal entries that are  actually processed.  In
       most applications this is the  number of data base add,  update,
       and  delete  operations  (some applications  may  have  a  large
       number  of data  queue entries or  data area  changes).   If you
       are  already  journaling,  use the  TAA  Print  Journal Analysis
       (PRTJRNANL) command  to get  an idea  of how  much activity  you
       have.

       Note that the  number of journal entries for  'open' and 'close'
       is  not a  significant factor.   APYRMTJRN only  opens each file
       once.

       However,  avoiding  the  existence  of  Open/Close  entries   is
       desirable as  this would result  in fewer entries  being written
       to  the  journal, fewer  entries sent  across  the communication
       line, and  fewer  entries  to be  considered  by  the  APYRMTJRN
       tool.    You  can omit  the  Open/Close  entries  by  specifying
       OMTJRNE(*OPNCLO)   on  the  STRJRNPF   command  (see   also  the
       STRJRNLIB command).

  **   The  number  of  objects  being  journaled  is  generally  not a
       significant factor  (maximum limit  is 32,767).   If the  number
       of objects in  the overflow table reaches a  specific point, the
       program  will refresh  itself.  This  is the  same function that
       occurs with SNDAPYRMTE OPTION(*REFRESH).

       If an object is  no longer needed in  the application, there  is
       no  significant performance  degradation in  leaving the  object
       in  the file used by  WRKAPYRMT.  The object  does count against
       the 32,767  limit.   The  record describing  the object  can  be
       deleted from the file using WRKAPYRMT.

       The listing  produced  by the  APYRMTJRN job  will also  provide
       you  with  information about  the  amount of  activity  for each
       object being journaled.

  **   A  good method  of periodically  checking the  performance is to
       enter on the local system:

            SNDAPYRMTE    JRN(xxx) OPTION(*TIMSTM)

       This  will cause  messages  to  be  sent to  the  message  queue
       specified on  CRT/CHGAPYRMTD when the entry is  processed on the
       remote  system.  The messages describe  how the APYRMTJRN job is
       keeping up with  applying entries.  See  the discussion for  the
       SNDAPYRMTE OPTION parameter.

  **   Remote  journal delivery  option.   Be sure  you understand  the
       DELIVERY option  specified on CHGRMTJRN.   *ASYNC is the default
       and provides the  best performance, but  not the best  recovery.

  **   Communication  line speed.    There  are many  alternatives  for
       this  ranging  from  opti-connect to  traditional  communication
       lines.   The  communication speed  can limit  what the APYRMTJRN
       job is capable of performing.

       Your   communication   speed    should   not   bottleneck    the
       application.    If  the  communication  line  is  a  bottleneck,
       entries  may  not  reach  the remote  system  and  you  would be
       exposed to  a  significant loss  of  data  if the  local  system
       fails.

  **   Run priority  of the  batch jobs.   The CRT/CHGAPYRMTD  commands
       allow  you to specify  a run  priority for the  APYRMTJRN master
       job and the APYRMTJRNn apply jobs.   The default is 50  (typical
       default for batch work).   The master batch job  (APYRMTJRN) may
       well be  a bottleneck which  you can improve  the performance of
       by providing a better job priority.

  **   Time  slice for  the master  job.   CRT/CHGAPYRMTD allow  you to
       specify the  time  slice that  will be  allowed  for the  master
       job.    The  default used  is  the  standard  batch value  of  5
       seconds.

  **   Wait  time  values.   CRT/CHGAPYRMTD  allow you  to  specify the
       wait time that  will be  used by  the master job  if no  entries
       exist in  the journal  to be  extracted.   You may also  specify
       the  wait time  for the apply  jobs if  no new entries  exist in
       the user space to be processed.   The listing produced from  the
       master  job  will  describe the  number  of  master  waits  that
       occurred.   The  optional listings  produced  by the  apply jobs
       will describe the number of waits for each.

       If  you specify  too low a  value, you will  probably see excess
       waits.   Each  wait  causes overhead  on  your  system.   It  is
       important  to remember  that  (assuming you  have enough  system
       power),  the  master and  apply  jobs will  eventually  catch up
       with the  number of entries  placed in  the journal.   The  most
       important  consideration is  to ensure  that  the entries  cross
       the  communication line  and exist  in  the journal  receiver on
       the remote system.

  **   Multiple  apply  jobs  may  be  specified  using  the  WRKAPYRMT
       command to request  an apply job  other than APYRMTJRN1.   Using
       multiple  apply jobs should  only be  considered if you  are not
       getting enough throughput from the default apply job.

       You  can  determine the  amount  of CPU  and  the number  of I/O
       Requests used  for the master  and apply  jobs by reviewing  the
       listings.    Both values  are  determined  just  prior to  final
       processing  for each  job.   Therefore,  this would  not include
       the time and I/O requests required to write out the table.

  **   Multiple journals  may provide  a processing  advantage  because
       each journal  uses a separate job  to extract the entries  and a
       separate job  (or jobs) to apply them.   Each journal requires a
       separate library  be named  for the  CRTAPYRMTD command.    This
       will create a  separate subsystem, job  queue, etc.   You should
       not   create   multiple  journals   unless   required  by   your
       application  or you are  bottlenecking on the  job that extracts
       journal entries (the default name is APYRMTJRN).

  **   The subsystem  created by  CRTAPYRMTD  uses *NOMAX  for the  the
       number of  jobs and  the only  pool is assigned  to *BASE.   You
       should consider changing these to meet your requirements.

Adding a new object to a running environment
--------------------------------------------

If  you need  to add  a new  object to an  application that  is already
using APYRMTJRN,  you must  first synchronize  the  object between  the
local and remote systems.   When journaling is started  to an object on
the local  system, APYRMTJRN will recognize  journal activity and start
applying the  entries  (the  corresponding object  must  exist  on  the
remote system).

There is no  need to tell APYRMTJRN of  a new object.  It  will attempt
to apply the journal entry to the corresponding object.

Once  the  object  is known  in  the  APYRMTP  file,  you may  describe
options using the WRKAPYRMT command.

Restarting APYRMTJRN after a normal shutdown
--------------------------------------------

If  APYRMTJRN is  shutdown by  SNDAPYRMTE or  ENDAPYRMT, proper restart
is to begin  at the journal entry  following the last entry  processed.
STRAPYRMT will do this by default.

For every  journal entry that causes  a change, the  sequence number of
the  journal entry is updated  in the APYRMTJRND  user space created by
CRTAPYRMTD.

The next  time you  use STRAPYRMT,  this sequence  number is  accessed,
bumped by  one, and is  used to begin processing.   This allows  you to
shutdown APYRMTJRN and restart at your convenience.

For  this recovery to work  properly, the last  journal entry processed
must exist  in the  receiver  chain.   If  you change  receivers,  good
practice would be  to retain the previous  receiver on line as  part of
the receiver  chain.  This  allows the APYRMTJRN  default processing to
occur.

If  APYRMTJRN is shutdown, you change to  a new receiver and delete the
old receiver, you  may lose entries and  the last entry processed  will
not  exist.    If  the  journal  receiver is  lost,  you  must  specify
SEQNBR(*FIRST)  (or a  specific sequence  number) on  STRAPYRMT command
to attempt recovery.  See the section on 'Recovery'.

The user spaces  used to hold  the entries contain  the location  where
the next entry will  be placed by the master job and  the next entry to
be processed  by the apply job.  These entries  are used if an abnormal
shutdown occurs.

Keeping the remote journal active
---------------------------------

There are two considerations:

  **   Ensuring the APYRMTJRN subsystem is  active.  This is  generally
       solved  by using  the  QSTRUPPGM  system  value to  include  the
       STRAPYRMT command as part of the startup of the system.

       There will  be times when you will want  to end the subsystem to
       perform  some  other task.    Because a  subsystem  controls the
       work, you  can use  the  ENDAPYRMT and  STRAPYRMT commands  when
       needed.

       The  APYRMTJRNC   job  is  a  never  ending   job  submitted  by
       STRAPYRMT  and wakes  up every  10 minutes to  see if  the other
       jobs are still active.  If not a message is sent.

  **   The more  critical  requirement is  to  ensure that  the  remote
       journal is in a *ACTIVE 'journal state'.

       If  the 'local'  system is  re-IPLed,  the state  of the  remote
       journal  becomes *INACTIVE.   There are  other reasons  that the
       remote journaling may also become inactive.

       The TAA command  CHKRMTJRN provides a  simple means of  checking
       the 'journal  state'.  An  escape message  (TAA9895) is sent  if
       the remote journal is not *ACTIVE.

The system supports two methods of activating the remote journal:

  **   Using  the WRKJRNA command,  then the  F16 key, and  then Option
       13.

  **   The  CHGRMTJRN  command  can  be  used  to  change  the 'journal
       state' such as:

             CHGRMTJRN    JRNSTATE(*ACTIVE)

You should  consider  writing  a never  ending  program for  the  local
system  that  periodically checks  remote  journaling.   The  following
describes  a simple solution  (you may need  to tailor  this code based
on your experience).

             PGM
             DCL        &JRNSTATE *CHAR LEN(10)
 CHECK:      CHKRMTJRN  SRCJRN(yyy)
             MONMSG     MSGID(TAA9895) EXEC(DO) /* *INACTIVE */
             CHGRMTJRN  RDB(xxx) SRCJRN(xxx) JRNSTATE(*ACTIVE)
             MONMSG     MSGID(CPF698F) /* Ignore msg from remote */
             GOTO       WAIT
             ENDDO      /* *INACTIVE */
             MONMSG     MSGID(TAA9896) EXEC(DO) /* *FAILED */
                        /* Wake up someone as the communication */
                        /*   line has probably failed           */
             SNDPGMMSG  MSG('...') TOMSGQ(xxx)
             GOTO       WAIT
             ENDDO      /* *FAILED */
             MONMSG     MSGID(TAA9897) EXEC(DO) /* *CTLINACT    */
                        /* Wake up someone as the state         */
                        /*   indicates a problem                */
             SNDPGMMSG  MSG('...') TOMSGQ(xxx)
             GOTO       WAIT
             ENDDO      /* *CTLINACT */
                        /* Journal state is still *ACTIVE */
 WAIT:                  /* The following wakes up every 5 minutes */
             DLYJOB     DLY(300)
             GOTO       CHECK
             ENDPGM

Recovery in the event of a failure
----------------------------------

Most recovery is handled automatically.  For example,

  **   If an  APYRMTJRN  job fails,  but  the  remote system  does  not
       abnormally  terminate, use  ENDAPYRMT  (or  ENDSBS) to  end  the
       function.    Then  use  STRAPYRMT.    As  long as  the  sequence
       numbers in  the user  spaces  and data  changes are  written  to
       disk, the function should recover without error.

  **   If  the communication  method  between  the two  systems  fails,
       recovery  is   attempted  by  the   system.    If   recovery  is
       unsuccessful,  the  communications  must  be  restarted,  but no
       entries are lost.

There are conditions  that may  cause objects to  become out of  synch.
For example,

  **   If the remote  system fails, some number of  journal entries may
       not  be  applied.    Because  applying  journal  entries  causes
       asynchronous writes to disk, some  entries may not exist.   This
       situation could  be minimized by  journaling the objects  on the
       remote system.

  **   If the  local system fails, not every  journal entry made on the
       local system  may  be passed  to  the  remote system.    If  the
       journal receiver can be recovered, no errors should occur.

       If the object  can be recovered,  but not the  journal receiver,
       you  have probably  lost some  entries.   This  may result  in a
       mismatch  between  the  two  systems.   If  this  type  of error
       occurs, you must resynch the objects.

In some  cases it  may be  necessary to start  the apply  process at  a
specific sequence number.  Do the following:

  **   On the 'remote' system, end the APYRMTJRN function:

            ENDAPYRMT

  **   On  the  'local' system  use  DSPJRN  to  determine the  journal
       sequence number you want to start at.

            DSPJRN     JRN(xxx/yyy)

       Note  the sequence number, the journal  receiver and library for
       use in the next step.

  **   Start  the  APYRMTJRN  job  on  the  'remote'  system  with  the
       sequence number and journal receiver name and library:

            STRAPYRMT   LIB(lll) JRNRCV(xxx/yyy) SEQNBR(nnn)

       The first entry processed should be what you requested.

Keeping the environment in synch
--------------------------------

APYRMTJRN is limited to the data portion of:

      - Data Base members
      - Data Areas
      - Data Queues

Any other  data in  objects (such  as Message  Queues, User Spaces,  or
Stream  files) that are critical  to your application,  must be handled
separately.

If you are going to use  the APYRMTJRN function for high  availability,
you must  have good control  over object changes,  authorizations, etc.

There  are TAA  Tools to  assist in  determining if  you are  in synch.
See the section on 'Comparing objects from different systems'.

Journal Codes/Types that are processed
--------------------------------------

Only  certain  journal  code/types  are  processed.    The  others  are
checked to  be  sure  they are  known  to  the processing  program  and
ignored.

For example,  not every 'R'  (Record) journal entry code  is processed.
The  following are  ignored as  they do not  impact the  replication of
data:

         IL = New increment occurred (increase in allocated space)
         UB = Before image (only after images are applied)
         BR = Before image for commit rollback

When  an  update  occurs  during  commitment  control  processing,  two
entries occur.  The  UB entry has the prior image of  the record and is
bypassed.   The UP entry (update) is processed  with the new image (the
data base is changed).

If a rollback  occurs, two entries  occur.  The BR  entry contains  the
same image  as the UP  entry and  is bypassed.   The UR entry  contains
the same  image as the  UB entry (the  original data) and  is processed
(the  data  base  is  changed).   This  resets  the  data  base  to the
original value.

The following journal  entry code/types are  processed (some result  in
error conditions).   If a code/type is  not in the list,  it is ignored
(no action occurs).

       Data record changes - Journal code = R

         DL = Delete
         DR = Delete for commit rollback
         PT = Put (write)
         PX = Put to a deleted relative record number
         UP = Update
         UR = After image for commit rollback

       Member changes - Journal code = F

         CR = Clear member
         IZ = Initialize member
         MD = Delete member
         MM = Move member - (caused by MOVOBJ) - Rejected
         MN = Rename member - (caused by RNMOBJ) - Rejected
         RG = Reorganize member - (caused by RGZPFM) - Rejected

       Data Area changes - Journal code = E

         EA = Change of data (either full or partial)
         EM = Move object - Rejected
         EN = Rename object - Rejected

       Data Queue changes - Journal code = Q

         QC = Non-keyed data queue clear
         QJ = Keyed data queue clear
         QK = Keyed data queue sent
         QL = Keyed data queue received
         QM = Move object - Rejected
         QN = Rename object - Rejected
         QR = Non-keyed data queue received
         QS = Non-keyed data queue sent

     SNDAPYRMTE changes - Journal type = U

         TT = Option types

Preparing for APYRMTJRN
-----------------------

Because  of the  32,000 byte length  restriction, you  should scan your
objects to determine if  any have a longer length.   Two TAA tools  are
provided and would normally be submitted to batch as:

             SCNDBFLEN     RCDLEN(32001) LIB(*ALLUSR)
             SCNDTAQLEN    MAXLEN(32001) LIB(*ALLUSR)

It is  desirable to  minimize the  number of  libraries that should  be
replicated  between the local and  remote systems.  This  will give you
less to manage.

Some users  prefer  to  separate  the data  libraries  (such  as  those
objects  being  journaled)  from  the  program   libraries.    This  is
essential  for  providing  minimum  downtime if  a  'save-while-active'
approach  is used.   Source data should probably  be kept separate from
the data libraries.

Reducing the  the number  of objects in  the library  of objects  being
journaled, has no advantage from an APYRMTJRN perspective.

If  you  have a  library  where all  objects  (that  can be  journaled)
should be journaled, you can force journaling by:

             STRJRNLIB     LIB(xxx) JRN(yyy)

STRJRNLIB  will start journaling to any  objects (data base files, data
areas, and data queues).

The  CHKJRNLIB  will  just  check  to  ensure  that  all   objects  are
journaled.

             STRJRNLIB     LIB(xxx) JRN(yyy)

If you  want to  review all  objects in a  library to  see if  they are
journaled, use:

             WRKJRNLIB     LIB(xxx) JRNOPT(*xxx)

The  JRNOPT parameter will allow  you to see those  that are journaled,
those that are not, or both.

You must  also ensure  that the  environments are  in synch.   See  the
section on 'Keeping the environment in synch'.

If you  are going  to use  APYRMTJRN as a  high availability  solution,
you  will probably  want  to journal  the  same objects  on  the remote
system.    You can  either journal  all of  the  time, or  when cutover
occurs, you can start journaling such as with STRJRNLIB.

Setting up remote journaling
----------------------------

For detail  information, see 'How  to setup  remote journaling' in  the
'I/Series System information center'.

The basic steps are:

  **   Determine the libraries  that will be used and  the objects that
       will  be replicated.   You normally want to  minimize the number
       of libraries involved  and include  only the  objects that  will
       be replicated.  This may require moving of objects.

  **   Create  the libraries  to be  replicated on  the remote  system.
       Using  the same  library and  object names  is a  requirement of
       the APYRMTJRN tool.

  **   Create a journal  receiver and  journal on the  local system  if
       not  already created.    You  can  have multiple  journals,  but
       CRTAPYRMTD requires  a unique library be used  for each journal.

  **   Follow  the instructions in  the next section  about 'Setting up
       remote journaling communications'.   You must have a  Relational
       Data Base (RDB) entry for the next step.

  **   Use  the   system  ADDRMTJRN  command  to   specify  the  remote
       journaling  function.    Specify the  RDB  name  you  entered on
       WRKRDBDIRE and the  name of the  local system journal.   If  the
       same journal  and journal  library name are  used on  the remote
       system,  take the defaults  for TGTJRN  and RMTRCVLIB.   Use the
       defaults   of   RMTJRNTYPE(*TYPE1)   and   DLTRCV(*NO).      The
       DLTRCV(*NO) function  is important  because you  do not want  to
       delete  a receiver  on  the  local system  before  APYRMTJRN has
       applied  the  entries.   It  is  normally better  to  manage the
       remote receivers separately.

       A typical command would be:

            ADDRMTJRN     RDB(xxx) SRCJRN(yyy/zzz) TEXT('...')

  **   Use WRKJRNA for the  local system journal and F16 to  'Work with
       remote  journal  information'.    The 'Journal  state'  must  be
       *ACTIVE  as  stated  in  the  section  on  'Keeping  the  Remote
       Journal *ACTIVE'.

       Use option 13 to activate  the remote journal function (F5  must
       be  used to  see any  change to  the status  after changing  the
       'journal  state').     An  alternate  means  of  activating  the
       journal is  to  use  the CHGRMTJRN  command  with  the  JRNSTATE
       parameter.

       You must  ensure that the  'Journal state'  is *ACTIVE in  order
       for  the remote journaling  function to  be functional.   If you
       re-IPL  the system  or the  communications line  fails, you will
       probably need to re-activate the journal.

  **   Synchronize the objects to  be replicated from the local  system
       to the remote system (such as a save and restore).

  **   Journal the objects on the local system if not already done.

  **   Use  CRTAPYRMTD on  the remote  system.   Name the  journal that
       exists  on  the remote  system.   If  you took  the  default for
       *SRCJRN on ADDRMTJRN,  the name of  the journal is  the same  on
       both the local and remote system.

       Name a message  queue that will be  in break mode on  the remote
       system  so  errors may  be  quickly reported.    The  default is
       QSYSOPR, but  since  this  message queue  may  need  significant
       attention as you begin  to use APYRMTJRN, you may  want a unique
       message  queue.   The message  queue can  be changed  later with
       CHGAPYRMTD.

  **   Use  STRAPYRMT  on  the  remote system  to  start  the APYRMTJRN
       tool.

  **   Begin operations on the  local system that cause changes  to the
       objects being replicated.

Setting up remote journaling communications
-------------------------------------------

There  are several  solutions for  how  to setup  communications.   The
following describes only a single solution:

  **   Ensure  that the  communications protocol  you have  selected to
       use is  configured and  active on  both systems.    You can  use
       TCP/IP or SNA.

  **   Use the  WRKRDBDIRE command  to add  the appropriate  relational
       data  base (RDB) directory  entry to  the local system  (you may
       already have one).   If  you use  *TCP, the type  entry must  be
       *IP.

  **   If you want  a simple test and  are using TCP/IP, enter  on both
       the local  and remote system the CHGDDMTCPA  command and specify
       PWDRQD(*NO).      To   utilize  this   setting,   use  ENDTCPSVR
       SERVER(*DDM) and then STRTCPSVR  SERVER(*DDM).  The *DDM  server
       is normally  started by the  system startup program  when TCP/IP
       is  started.   If TCP/IP  is ended,  you may  need to  start the
       *DDM server with the STRTCPSVR command.

Back up of the remote system
----------------------------

Because the  APYRMTJRN jobs  are  updating user  spaces and  data  base
files, you  cannot perform a  backup of  the libraries involved  if the
jobs  are active.   Use ENDAPYRMT  to shut  down the subsystem  and the
jobs.

If journal  entries are  still occurring,  they will  be added  to  the
existing  receiver.    When  APYRMTJRN  is  restarted,  it  will  begin
applying where it left off.

If  you are  using APYRMTJRN  to allow  backup to  occur on  the remote
system  instead of the  local, you must shutdown  APYRMTJRN in order to
do the backup.  This  presents two considerations: 1) How long  will it
take  to do  the backup  as journal  entries are  not being  applied at
this  time 2) How long will  it take to apply  the journal entries that
are being held.

The best solution is generally to  minimize the backup time.  This  can
be done  using the system  'save-while-active' function.   Consider the
TAA tool SAVACT.

Comparing objects from different systems
----------------------------------------

To ensure  that your objects are in synch, you  can save the objects on
the local system and restore them  on the remote system to a  different
library.   Comparisons of  the objects can  then be  made for  both the
attributes and the data.

To compare the data consider:

   Data Base     The  system  supports the  CMPPFM  command.   The  TAA
                 CMPDBF  command  should also  be considered.   Compare
                 commands are effective on relatively small files.

                 For  large   files,  you  should   consider  the   TAA
                 CLCDBFHSH  tool.  It  allows you  to calculate  a hash
                 value  for the  records in  a member and  then compare
                 the value to the hash  results for the same member  on
                 the remote  system.   You may output  a file  with the
                 results  and compare with the  CMPDBFHSH command.  You
                 may also use  the 'block count'  function to  generate
                 a hash value for  segments of the file (such  as every
                 50,000 records)  and then decreasing  smaller segments
                 to  help identify the  records that are  not the same.

   Data Area     The TAA CMPDTAARA command may be used.

   Data Queue    The TAA CMPDTAQE command may be used.

Error numbers described in messages
-----------------------------------

If an  error number  is described  in a  message, the  message text  is
usually  sufficient to  determine what  the problem  is.   In addition,
when   the  APYRMTJRN  job  completes,  the   listing  will  contain  a
description of the errors that have occurred.

The following lists the message IDs that may be produced:"

   001           The length of a data  base file record exceeds  32,000
                 bytes (maximum supported).

   002           Journal  activity occurred  for  an  object that  does
                 not exist.

   003           An  object  size  (data  base  record  length or  data
                 queue maximum entry length) exceeds 32,000 bytes.

   004           The  record  length  of  a  data  base  record  has  a
                 different length than the journal entry.

   005           The  data queue  entry  length  of the  journal  entry
                 exceeds  the  maximum length  described  for the  data
                 queue.

   006           The  data area length has  been exceeded by the length
                 of the entry in the journal.

   007           The add  of  a relative  record  number failed.    The
                 probable  cause  is:  1)  The relative  record  number
                 where  the record  was added  does not agree  with the
                 relative record number of the  journal entry or 2)  An
                 error such  as a  'duplicate key'  has occurred.   The
                 error text includes the error message ID.

   010           A  journal entry  for a delete  failed.   The probable
                 cause is the relative  record number where the  record
                 was to occur  does not exist  or is already  a deleted
                 record.   The  error text  includes the  error message
                 ID.

   011           A  journal entry for  an update failed.   The probable
                 cause is:  1)  The relative  record  number where  the
                 update was  to occur  does not exist  or is  a deleted
                 record  or 2) An  error such as a  'duplicate key' has
                 occurred.  The error  text includes the error  message
                 ID.

   012           A  command  failed.    The  error  text  includes  the
                 command.

   013           Unable  to close  a member.   The error  text includes
                 the error message ID.

   014           A journal  entry  specified  a  RGZPFM  which  is  not
                 supported by the  tool.  See the section  on 'RGZPFM'.

   015           A  journal entry  specified a  MOVOBJ or  RNMOBJ which
                 is  not supported  by the  tool.   See the  section on
                 'MOVOBJ/RNMOBJ'.

   016           Unable to  open a  member.   The  error text  includes
                 the error message ID.

   017           CHGDTAARA failed.   The error text  includes the error
                 message ID.

   018           The  call  to  QSNDDTAQ failed  attempting  to  send a
                 data queue entry.  The  error text includes the  error
                 message ID.

   019           The call  to QRCVDTAQ  failed attempting to  receive a
                 data queue  entry.  The error  text includes the error
                 message ID.

   020           The call  to the  QCLRDTAQ  API failed  attempting  to
                 clear  a data  queue.   The  error  text includes  the
                 error message ID.

   021           A  CLRPFM command  failed.   The  error  text includes
                 the error message ID.

   022           An  INZPFM command  failed.   The error  text includes
                 the error message ID.

   023           A RMVM command  failed.  The  error text includes  the
                 error message ID.

   024           An  ADDPFM command  failed.   The error  text includes
                 the error message ID.

   025           A  mismatch in an  Array ID has occurred.   Inform the
                 TAA Productivity Tools owner of the error.

   026           The  apply  program  did  not  recognize  the  journal
                 code/type.   Inform the  TAA Productivity  Tools owner
                 of the error.

   027           The  apply program did  not recognize  the option from
                 SNDAPYRMTE.  Inform the  TAA Productivity Tools  owner
                 of the error.

   044           An  unknown  error  has  occurred.    Inform  the  TAA
                 Productivity Tools owner of the error.

APYRMTJRN Tool escape messages you can monitor for
--------------------------------------------------

A few commands send unique escape messages:

      STRAPYRMT   TAA9891    Sequence number not found.

Most  of the  programs do not  send escape  messages.   Escape messages
from based on functions will be re-sent.

CRTAPYRMTD Command parameters                         *CMD
-----------------------------

   JRN           The  qualified name  of the  journal to  be processed.
                 The library defaults  to *LIBL.   *CURLIB may also  be
                 entered.

   MSGQ          The  qualified name  of the  message queue  to receive
                 error  messages during the running  of APYRMTJRN.  The
                 default is QSYSOPR.   The  library defaults to  *LIBL.
                 *CURLIB may also be entered.

   JOBD          The qualified  name of  the job description  to submit
                 the APYRMTJRN  jobs with.  The  default is QDFTJOBD in
                 QGPL.  The library value may be *LIBL or *CURLIB.

   APYRMTLIB     The library  name where  the objects  will be  created
                 that  are  used   during  processing.     The  default
                 library name is APYRMTJRN.

   RESET         A  *YES/*NO option for  whether to reset  the activity
                 statistics  each time APYRMTJRN is  used.  The default
                 is  *YES.    In  most  environments,  the  default  is
                 probably adequate.

                 For example,  if APYRMTJRN is  shutdown at the  end of
                 each  day, the listing produced at  the end of the job
                 will have activity  statistics for  the complete  day.
                 If you  do not shut  down APYRMTJRN for  several days,
                 you may  want to use SNDAPYRMTE  OPTION(*PRINT) at the
                 end   of    the    day    followed    by    SNDAPYRMTE
                 OPTION(*INZSTAT).

                 If *NO  is entered,  the statistics  will continue  to
                 accumulate   until   SNDAPYRMTE  OPTION(*INZSTAT)   is
                 used.

   PRTAPYSTAT    A  *YES/*NO  value for  whether  to output  a separate
                 spooled file describing the  activity for each of  the
                 batch apply jobs.   The default is *YES,  to produce a
                 listing  for each of  the actual apply  jobs that were
                 active.

                 *NO may be used to  prevent the listing for any  batch
                 apply job.

                 The  master  apply  job (default  name  is  APYRMTJRN)
                 which  extracts the journal entries  always produces a
                 listing.

   FRCJOBLOG     A *YES/*NO value for  whether to force  a job log  for
                 each batch job.   The default is *YES meaning  the job
                 log will be created even if the job ends normally.

                 *NO  may be  specified  to  prevent the  job  log from
                 being output unless the job ends abnormally.

   APYREFITG     A  *YES/*NO value for whether  to apply entries caused
                 by a  Referential Integrity  constraint.  The  default
                 is *NO  meaning the  entries will be  bypassed because
                 the  Referential  Integrity constraints  are identical
                 between the local and remote  systems.  This would  be
                 normal if you  are using the remote system  for a high
                 availability   solution  and  the   ADDPFCST  function
                 exists on both  systems.  See  the tool  documentation
                 for a further explanation.

                 *YES  may be  specified  to cause  the  entries to  be
                 applied.   This would be  normal if the  remote system
                 is   used   for   backup  and   not   used   for  high
                 availability.

   APYTRIGGER    A *YES/*NO value for  whether to apply entries  caused
                 by  a Trigger  program.   The default  is  *NO meaning
                 the  entries  will  be  bypassed  because  the Trigger
                 programs are identical  between the  local and  remote
                 systems.   This would be normal  if you are  using the
                 remote  system for  a  high availability  solution and
                 the ADDPFTRG  function exists  on both  systems.   See
                 the tool documentation for a further explanation.

                 *YES  may be  specified  to cause  the  entries to  be
                 applied.   This would be  normal if the  remote system
                 is   used   for   backup  and   not   used   for  high
                 availability.

   MSTPTY        The   run   priority   of   the   master   batch   job
                 (APYRMTJRN).   The default is  50.  The value  must be
                 between   01  and  99.    There   will  always  be  an
                 APYRMTJRN job running when STRAPYRMT is used.

   APY1PTY       The run priority  of the  APYRMTJRN1 batch  job.   The
                 default  is 50.   There  will always  be a  APYRMTJRN1
                 job  running when STRAPYRMT  is used.   The value must
                 be between 01 and 99.

   APY2PTY       The run priority of the  APYRMTJRN2 batch job if  any.
                 The default is 50.   The value must be  between 01 and
                 99.

   APY3PTY       The run  priority of the APYRMTJRN3 batch  job if any.
                 The  default is 50.  The  value must be between 01 and
                 99.

   APY4PTY       The run priority of  the APYRMTJRN4 batch job if  any.
                 The default is  50.  The value must  be between 01 and
                 99.

   APY5PTY       The  run priority of the APYRMTJRN5  batch job if any.
                 The default is 50.   The value must be between 01  and
                 99.

   APY6PTY       The run priority  of the APYRMTJRN6 batch  job if any.
                 The default  is 50.  The value  must be between 01 and
                 99.

   APY7PTY       The run priority of the  APYRMTJRN7 batch job if  any.
                 The default is 50.   The value must be  between 01 and
                 99.

   APY8PTY       The run  priority of the APYRMTJRN8 batch  job if any.
                 The  default is 50.  The  value must be between 01 and
                 99.

   APY9PTY       The run priority of  the APYRMTJRN9 batch job  if any.
                 The default is  50.  The value must  be between 01 and
                 99.

   MSTTIMSLC     The  time slice of  the master APYRMTJRN  batch job if
                 any.   The  default  is  5000.    The  value  must  be
                 between 1 and 9,999,999.

   MSTWAITTIM    The number of  seconds the master APYRMTJRN  batch job
                 waits   when  there   are  no  more   journal  entries
                 available from  the  remote  journal  receiver.    The
                 default is  2 seconds.   The value  must be between  1
                 and 600.

                 The lower  the value, the more current  you will be in
                 updating  objects  on the  remote  system.   Note that
                 since the journal  entries are  placed in the  journal
                 receiver  by the  system, the  replication of  data is
                 no safer by providing a lower value.

                 The  spooled  file  produced by  the  master  job will
                 describe the  number  of  waits that  occurred.    The
                 more   waits  that   occur,  the   more  overhead   is
                 performed.

   APYWAITTIM    The  number  of seconds  each apply  batch  job should
                 wait  when   there  are   no  more   journal   entries
                 available from  the  user space  to be  applied.   The
                 default  is 3 seconds.   The  value must be  between 1
                 and 600.

                 The  lower the value, the more  current you will be in
                 updating objects  on  the remote  system.   Note  that
                 since the  journal entries  are placed in  the journal
                 receiver  by the system  and in the user  space by the
                 master job, the  replication of  data is  no safer  by
                 providing a lower value.

                 The  spooled file  optionally produced  for the  apply
                 jobs   will  describe   the   number  of   waits  that
                 occurred.    The  more  waits  that  occur,  the  more
                 overhead is performed.

   SRCLIB        The  source  library  to  use  for  the  QATTDDS  file
                 source.    The default  is  *TAAARC.   in  the TAATOOL
                 library.

                 A  specific user library may  be named, but the source
                 file must be QATTDDS.

   AUT           The authority to be  placed on the APYRMTP file  which
                 contains one  record per object being  journaled.  The
                 default is *USE.

                 *CHANGE or *EXCLUDE may be entered.

DLTAPYRMTD Command parameters                         *CMD
-----------------------------

   APYRMTLIB     The  library  name where  the objects  exist  that are
                 used  by the  APYRMTJRN  tool.    A  library  must  be
                 named.

STRAPYRMT Command parameters                          *CMD
----------------------------

   APYRMTLIB     The  library name  where  the objects  exist that  are
                 used   by  the  APYRMTJRN   tool.     The  default  is
                 APYRMTJRN.

   JRNRCV        The beginning journal  receiver to use.   The  default
                 is *LASTPCS for  the last journal receiver used.   The
                 value of *CURCHAIN is used for RTVJRNE.

                 *FIRST  may be  specified  to mean  the  first journal
                 receiver in the chain.

                 A   specific  journal  receiver  and  library  may  be
                 entered.

   SEQNBR        The   journal   entry   sequence   number   to   begin
                 processing  with.   The  default  is *LASTPCS  meaning
                 the  sequence  number  that is  one  greater  than the
                 last  journal  entry  processed  (processed  means  an
                 entry that caused a change such as an update).

                 If  you have  never  used  STRAPYRMT before,  *LASTPCS
                 will be changed internally to *FIRST.

                 *FIRST may  be entered to mean the  first entry in the
                 first receiver of the receiver chain.

                 If the APYRMTJRN  job was shutdown,  you changed to  a
                 new receiver  and deleted the  old receiver,  the last
                 journal  entry   processed  will  not   exist  in  the
                 receiver  chain.    If  this  is  the  case,  you must
                 specify *FIRST to begin processing.

   TSTLIB        The test library  if you are  running a test to  apply
                 entries to  a test library  on the local system.   The
                 default  is  *NONE meaning  the library  found  in the
                 journal entry will be used to apply to the object.

                 If a  test library  is named,  the APYRMTJRN  function
                 will use  the TSTLIB name instead  of the name  in the
                 journal  entry.   This  function should  only  be used
                 when you  are  testing the  APYRMTJRN  function  using
                 only the local system.

   TSTOPTION     A test option.   The default is *NONE meaning  this is
                 not  a   test.    Other  options   allow  entries  for
                 debugging.

                 You  should  use  *NONE  unless  directed  by  the TAA
                 Productivity Tools owner.

ENDAPYRMT Command parameters                          *CMD
----------------------------

   APYRMTLIB     The library  name  where the  objects  exist that  are
                 used  by   the  APYRMTJRN   tool.    The   default  is
                 APYRMTJRN.

SNDAPYRMTE Command parameters                         *CMD
-----------------------------

   JRN           The  qualified  name  of  the  journal  on  the  local
                 system that the  entry will be sent  to.  The  library
                 defaults to *LIBL.  *CURLIB may also be specified.

                 The  option   requested  will  occur  on   the  remote
                 system.

   OPTION        The option to be taken.

        *STROBJ       This  is intended to  be used after  an error has
                      occurred such  as an  object did  not exist  when
                      journal activity occurred  or a data  base member
                      got  out of  synch between  the local  and remote
                      systems.   You  must enter the  OBJ parameter for
                      a specific object.

                      Once an error  has occurred, any journal  entries
                      for  the object  are ignored  (see WRKAPYRMT  for
                      the  *EDT  'recovery'  option  that  allows  some
                      continuation).   You  must  resynch  the  objects
                      first    before    using     *STROBJ.        Once
                      synchronization  has been  achieved you  can then
                      use *STROBJ.

                      *STROBJ is  not needed  if the  resynch  occurred
                      while APYRMTJRN  was shutdown.   The next  use of
                      APYRMTJRN   would    begin   normal   processing.
                      *REFRESH will also act in the same manner.

                      Note  that  *STROBJ is  not needed  if you  add a
                      new  object   to  both   the  local  and   remote
                      systems.    As  soon   as  any  journal  activity
                      occurs,  APYRMTJRN  will  attempt  to  apply  the
                      entry.

                      A  message  is  sent  to  the  specified  message
                      queue when *STROBJ is used.

        *ENDOBJ       This is  intended to be used  if you need  to end
                      applying  journal entries.    The object  will be
                      marked as 'in error'  and any additional  journal
                      entries will  be bypassed.   If a file  object is
                      specified  and the  member was  open,  the member
                      is closed.

                      For  example, a  RGZPFM journal  entry will cause
                      an error.    If you  are  going to  reorganize  a
                      file   on  the  local   system,  you   could  end
                      applying entries on the remote system.

                      If  the internal table  is refreshed or APYRMTJRN
                      is shutdown  and restarted,  the object  will  no
                      longer be marked as 'in error'.

                      A  message  is  sent  to  the  specified  message
                      queue when *ENDOBJ is used.

        *CPY          Copies  the object to  itself.   This function is
                      designed to  synchronize the  object between  the
                      local and  remote system  either because: 1)  the
                      object is  out of synch or 2)  you want to ensure
                      it is in synch.

                      Copying  the  object  to  itself  causes  journal
                      entries  to be  made  which  flow to  the  remote
                      system and are applied normally.

                      An   exclusive  lock   (*EXCL)  is   required  to
                      perform  the copy  function.   At  the completion
                      of the SNDAPYRMTE command,  it is safe to  resume
                      making application changes to the object.

                      The  *CPY  option  is  only  practical  on  small
                      objects  during   peak  hours.    During  offpeak
                      hours, you  may use  *CPY  for larger  data  base
                      objects,  but  you  must  be   prepared  for  the
                      performance    implications   of    adding   many
                      entries.

                      The  TAAWORK  library  (on the  local  system) is
                      used as  a  staging area  for the  objects  being
                      copied.   The  basic approach  is: 1)  A  copy of
                      the  object  is made  in TAAWORK  along  with the
                      current data 2)  The original  object is  cleared
                      3) The  data is copied  back from TAAWORK  to the
                      original  object.   The  TAAWORK version  is then
                      deleted.

                      If the object was  in error, clearing the  object
                      causes  a journal  entry to  be  made which  will
                      reset the object (*STROBJ is not needed).

                      Note  that  for  data  base files,  the  relative
                      record   numbers  will  be   changed  if  deleted
                      records exist in  the original file.   You should
                      not  use this  function if  you are  dependent on
                      the  original  relative  record  numbers  in  the
                      file.

        *FORCE        The *FORCE function cause  a journal entry to  be
                      forced.   This  causes  buffered journal  entries
                      to  be forced  to the journal.   It  performs the
                      function of SNDJRNE  FORCE(*YES).   The entry  is
                      ignored on the remote system.

        *INZSTAT      Initialize  the statistics  that  are being  kept
                      for  activity.  This  does not end  the APYRMTJRN
                      job.      See   also  the   RESET   parameter  on
                      CRTAPYRMTD.

        *PRINT        Print the internal  tables of the APYRMTJRN  job.
                      This  allows  for  printing  the table  of  known
                      objects  and overflow objects  during the running
                      of APYRMTJRN.   This does  not end the  APYRMTJRN
                      job.   The  activity  statistics  are not  reset.
                      The  intent   of  the  function  is  to  allow  a
                      periodic review of activity.

                      Note that the listings  from the APYRMTJRNn  jobs
                      are not printed by this function.

        *REFRESH      Refreshes  the  internal  table   by  ending  the
                      processing  program  and   restarting  it.    The
                      activity  statistics  are  not reset.    When the
                      program is  ended,  the APYRMTP  file is  written
                      out and  then read back  in again.  A  purpose of
                      this  option is to allow a  refresh if the number
                      of overflow  entries  is  getting  large  or  the
                      amount of  activity for  the overflow  entries is
                      large.     Refreshing  provides  somewhat  better
                      performance as  the  overflow entry  table  takes
                      longer to process.

                      Refreshing  takes some  time  and should  not  be
                      used  frequently.   An  automatic  refresh occurs
                      if  the overflow table  reaches a specific number
                      of entries.

        *SHUTDOWN     This  ends  the   APYRMTJRN  jobs  in  a   normal
                      manner.   The internal tables are  written to the
                      APYRMTP  file,  a  listing  is  created,  and the
                      subsystem is ended.

        *TIMSTM       This special entry  sends three  messages to  the
                      specified message queue:

                      1)  From  the  master  job  describing  when  the
                      SNDAPYRMTE  command was run on  the local system.
                      Note that  the  time displayed  on  the  'remote'
                      system  will be  the  clock  time of  the  'local
                      system'.   The  clocks  of the  local  and remote
                      system  must  be  in  synch  to  make  the  first
                      message meaningful versus the second message.

                      2)  From  the  master  job  describing  when  the
                      SNDAPYRMTE  entry  was  processed by  the  master
                      job

                      3)  From   the  apply  job  describing  when  the
                      SNDAPYRMTE entry was processed.

                      The time values  appear in  a time-stamp  format.
                      This  allows  a  periodic   review  of  how  fast
                      journal  entries are being applied  on the remote
                      system.

   OBJ           This is 4  part parameter for  object, library,  type,
                 and member.  The member value defaults to *NONE.

                 You must specify an  object to be operated on  for the
                 options *STROBJ, *ENDOBJ, and *CPY.

                 For  data  areas and  data  queues,  the member  value
                 must be *NONE.

                 For  a  *FILE  object,  a  member  must  be specified.
                 *FIRST may be used or  a specific name.  If  *FIRST is
                 used,  the name of  the member  is established  on the
                 local  system  and the  specific member  name  will be
                 used on the  remote system  (not the  first member  of
                 the file).

                 The  other options  (such as  *SHUTDOWN), require  the
                 object  name, library,  and type to  be blank  and the
                 member value be *NONE.

DSPAPYRMTD Command parameters                         *CMD
-----------------------------

   APYRMTLIB     The   library   containing   the   objects   used   by
                 APYRMTJRN.  The default is APYRMTJRN.

CHGAPYRMTD Command parameters                         *CMD
-----------------------------

   APYRMTLIB     The library  containing  the user  space object  which
                 has  the  description  for  the  APYRMTJRN job.    The
                 default is APYRMTJRN.

                 The  command  may  only be  used  interactively.   The
                 command  extracts   the   current  values   from   the
                 APYRMTJRND   user   space   and  prompts   using   the
                 CHGAPYRMT2 command.

CHGAPYRMT2 Command parameters                         *CMD
-----------------------------

   JRN           The  qualified name  of the  journal to  be processed.
                 The default  is  *SAME.    *LIBL  or  *CURLIB  may  be
                 entered for the library.

   MSGQ          The qualified  name of  the message  queue to  receive
                 error  messages during  the  running of  the APYRMTJRN
                 job.  The default is *SAME.   *LIBL or *CURLIB may  be
                 entered for the library.

   JOBD          The  qualified  name  of the  job  description  to  be
                 used.  The default is *SAME.

   APYRMTLIB     The   library   containing   the   objects   used   by
                 APYRMTJRN.  The default is APYRMTJRN.

   RESET         A  *YES/*NO option  for whether to  reset the activity
                 statistics each time APYRMTJRN  is used.  The  default
                 is  *SAME meaning to  retain the  current option.   In
                 most  environments, the  default  of *YES  is probably
                 adequate.

                 For example, if  APYRMTJRN is shutdown  at the end  of
                 each day, the  listing produced at the end  of the job
                 will  have activity  statistics for the  complete day.
                 If you do  not shut down  APYRMTJRN for several  days,
                 you may want  to use SNDAPYRMTE OPTION(*PRINT)  at the
                 end    of    the    day   followed    by    SNDAPYRMTE
                 OPTION(*INZSTAT).

                 If  *NO is  entered, the  statistics will  continue to
                 accumulate   until  SNDAPYRMTE   OPTION(*INZSTAT)   is
                 used.

   PRTAPYSTAT    Whether  to print  the statistics  kept by  each apply
                 job  (a  listing always  occurs for  the  master job).
                 *SAME is the default.

                 *YES causes  the statistics  to  be printed  for  each
                 apply job.

                 *NO  prevents the  statistics from  being printed  for
                 each apply job.

   FRCJOBLOG     A  *YES/*NO value for whether  to force a  job log for
                 each batch  job.   The  default  is *SAME  meaning  to
                 retain the current option.

                 *YES may be specified  to force a job log  for each of
                 the batch jobs.

                 *NO  may be specified  to prevent  the job log  if the
                 job completes normally.

   APYREFITG     A  *YES/*NO value for whether  to apply entries caused
                 by a  Referential Integrity constraint.   The  default
                 is *SAME meaning to retain the current option.

                 *NO  means the  entries will  be bypassed  because the
                 Referential   Integrity   constraints   are  identical
                 between the local and remote  systems.  This would  be
                 normal if you  are using the remote system  for a high
                 availability   solution  and  the   ADDPFCST  function
                 exists on both  systems.  See  the tool  documentation
                 for a further explanation.

                 *YES  may be  specified  to cause  the  entries to  be
                 applied.   This would be  normal if the  remote system
                 is   used   for   backup  and   not   used   for  high
                 availability.

   APYTRIGGER    A *YES/*NO value  for whether to apply  entries caused
                 by a  Trigger program.   The default is  *SAME meaning
                 to retain the current option.

                 *NO  means the  entries will  be bypassed  because the
                 Trigger programs are identical  between the local  and
                 remote  systems.   This  would be  normal  if you  are
                 using  the  remote  system  for  a  high  availability
                 solution and  the  ADDPFTRG function  exists  on  both
                 systems.   See the  tool documentation  for a  further
                 explanation.

                 *YES  may  be specified  to  cause the  entries  to be
                 applied.   This would  be normal if  the remote system
                 is  used   for   backup   and  not   used   for   high
                 availability.

   MSTPTY        The   run   priority   of   the   master   batch   job
                 (APYRMTJRN).   The default  is *SAME.   The value must
                 be between 01 and 99.

   APY1PTY       The run priority  of the  APYRMTJRN1 batch  job.   The
                 default is  *SAME.  The value  must be between  01 and
                 99.

   APY2PTY       The  run priority  of the APYRMTJRN2  batch job  if it
                 is submitted.  The default  is *SAME.  The value  must
                 be between 01 and 99.

   APY3PTY       The run  priority of  the APYRMTJRN3  batch job if  it
                 is submitted.   The default is *SAME.   The value must
                 be between 01 and 99.

   APY4PTY       The  run priority  of the  APYRMTJRN4 batch  job if it
                 is submitted.  The  default is *SAME.  The  value must
                 be between 01 and 99.

   APY5PTY       The  run priority of  the APYRMTJRN5  batch job  if it
                 is  submitted.  The default is  *SAME.  The value must
                 be between 01 and 99.

   APY6PTY       The run priority  of the  APYRMTJRN6 batch  job if  it
                 is submitted.   The default is *SAME.   The value must
                 be between 01 and 99.

   APY7PTY       The  run priority  of the APYRMTJRN7  batch job  if it
                 is submitted.  The default  is *SAME.  The value  must
                 be between 01 and 99.

   APY8PTY       The run  priority of  the APYRMTJRN8  batch job if  it
                 is submitted.   The default is *SAME.   The value must
                 be between 01 and 99.

   APY9PTY       The  run priority  of the  APYRMTJRN9 batch  job if it
                 is submitted.  The  default is *SAME.  The  value must
                 be between 01 and 99.

   MSTTIMSLC     The time  slice of the  master APYRMTJRN batch  job if
                 any.    The  default  is *SAME.    The  value  must be
                 between 1 and 9,999,999.

   MSTWAITTIM    The number of seconds  the master APYRMTJRN batch  job
                 waits  when   there  are   no  more   journal  entries
                 available  from  the  remote  journal  receiver.   The
                 default is *SAME.   The  value must be  between 1  and
                 600.

                 The lower the value,  the more current you will  be in
                 updating  objects on  the  remote system.    Note that
                 since  the journal  entries are placed  in the journal
                 receiver by  the system,  the replication  of data  is
                 no safer by providing a lower value.

                 The  spooled  file produced  by  the  master job  will
                 describe  the  number  of waits  that  occurred.   The
                 more  waits   that  occur,   the  more   overhead   is
                 performed.

   APYWAITTIM    The  number of  seconds  each  apply batch  job  waits
                 when  there  are  no  more  journal entries  available
                 from the user space  to be applied.   The entries  are
                 placed in  the  user space  by the  master  job.   The
                 default  is *SAME.   The value  must be between  1 and
                 600.

                 The  lower the value, the more  current you will be in
                 updating objects  on  the remote  system.   Note  that
                 since the  journal entries  are placed in  the journal
                 receiver  by the system  and in the user  space by the
                 master job, the  replication of  data is  no safer  by
                 providing a lower value.

                 The  spooled file  optionally produced  for the  apply
                 jobs   will  describe   the   number  of   waits  that
                 occurred.    The  more  waits  that  occur,  the  more
                 overhead is performed.

WRKAPYRMT Command parameters                          *CMD
----------------------------

   APYRMTLIB     The   library   containing   the   objects   used   by
                 APYRMTJRN.  The default is APYRMTJRN.

   EXIST         A  selection option  for whether  you want  to display
                 an  object if it  exists.  The default  is *ALL to see
                 both objects that exist  and those that do not.   Once
                 an  object  has  a  journal  entry to  be  applied,  a
                 record  is kept  in the APYRMTP  file.   If the object
                 is deleted, the record still exists.

                 *YES may be  entered to  see only  those objects  that
                 still exist.

                 *NO may  be entered to see  only those that  no longer
                 exist.   You  can use  the delete  option on  the work
                 display to clean up old objects.

   BATCHJOB      A selection option  for whether you  want to see  only
                 those  objects that  will  be  applied by  a  specific
                 batch job.

                 *ALL   is   the  default   to   display  all   records
                 regardless of which batch job does the apply.

                 A  1-9  value may  be  entered to  display  only those
                 jobs   that  will   be   applied   by   APYRMTJRN1   -
                 APYRMTJRN9.

RTVAPYRMTD Command parameters                         *CMD
-----------------------------

   APYRMTLIB     The   library   containing   the   objects   used   by
                 APYRMTJRN.  The default is APYRMTJRN.

   JRN           The  journal  name.   This  is  an  optional parameter
                 that if used must be specified as *CHAR LEN(10).

   JRNLIB        The  journal  library  name.    This  is  an  optional
                 parameter  that if  used  must be  specified as  *CHAR
                 LEN(10).

   MSGQ          The   message   queue   assigned   to  the   APYRMTJRN
                 function.   This  is  an optional  parameter  that  if
                 used must be specified as *CHAR LEN(10).

   MSGQLIB       The message  queue library  assigned to the  APYRMTJRN
                 function.    This is  an  optional  parameter that  if
                 used must be specified as *CHAR LEN(10).

   SBSD          The  subsystem  assigned  to  the  APYRMTJRN function.
                 This is  an optional  parameter that if  used must  be
                 specified as *CHAR LEN(10).

   SBSDLIB       The  subsystem  library   assigned  to  the  APYRMTJRN
                 function.    This  is an  optional  parameter  that if
                 used must be specified as *CHAR LEN(10).

   JOBQ          The job  queue  assigned to  the  APYRMTJRN  function.
                 This is  an optional  parameter that  if used must  be
                 specified as *CHAR LEN(10).

   JOBQLIB       The  job  queue  library  assigned  to  the  APYRMTJRN
                 function.   This  is  an optional  parameter  that  if
                 used must be specified as *CHAR LEN(10).

   JOBD          The  job   description  assigned   to  the   APYRMTJRN
                 function.    This is  an  optional  parameter that  if
                 used must be specified as *CHAR LEN(10).

   JOBDLIB       The   job   description   library   assigned   to  the
                 APYRMTJRN function.   This  is  an optional  parameter
                 that if used must be specified as *CHAR LEN(10).

   RESET         The reset  option assigned to  the APYRMTJRN function.
                 A  *YES  or  *NO  value  is  returned.    This  is  an
                 optional parameter that if  used must be specified  as
                 *CHAR LEN(4).

   PRTAPYSTAT    The  'print  apply  job   statistics'  option  to  the
                 APYRMTJRN  function.   A *YES  or  *NO values  will be
                 returned.   This  is  an optional  parameter  that  if
                 used must be specified as *CHAR LEN(4).

   LSTSEQNBR     The last journal  sequence number processed.   This is
                 an optional  parameter that if used  must be specified
                 as *CHAR LEN(10).

   LSTJRNRCV     The  last  journal  receiver processed.    This  is an
                 optional parameter that  if used must be  specified as
                 *CHAR LEN(10).

   LSTJRNRCVL    The library  of the  last journal  receiver processed.
                 This  is an  optional parameter  that if used  must be
                 specified as *CHAR LEN(10).

   FRCJOBLOG     The  'force   job  log'   option  to   the   APYRMTJRN
                 function.   A  *YES  or *NO  value  will be  returned.
                 This  is an  optional parameter that  if used  must be
                 specified as *CHAR LEN(4).

   APYREFITG     The 'apply  referential integrity  entries' option  to
                 the APYRMTJRN function.   A *YES or *NO value  will be
                 returned.    This is  an  optional  parameter that  if
                 used must be specified as *CHAR LEN(4).

   APYTRIGGER    The  'apply trigger  entries' option  to the APYRMTJRN
                 function.   A  *YES or  *NO  value will  be  returned.
                 This  is an optional  parameter that  if used  must be
                 specified as *CHAR LEN(4).

   MSTPTY        The  run time  priority assigned  to the  master batch
                 job.   A value  between 01  and 99  will be  returned.
                 This is  an optional  parameter that  if used  must be
                 specified as *CHAR LEN(2).

   APY1PTY       The  run  time  priority  assigned  to the  APYRMTJRN1
                 batch job.   A value  between 01 and  99 is  returned.
                 This is  an optional  parameter that  if used must  be
                 specified as *CHAR LEN(2).

   APY2PTY       The  run  time  priority  assigned to  the  APYRMTJRN2
                 batch  job.   A value between  01 and  99 is returned.
                 This is  an optional  parameter that if  used must  be
                 specified as *CHAR LEN(2).

   APY3PTY       The  run  time  priority  assigned to  the  APYRMTJRN3
                 batch  job.   A value between  01 and  99 is returned.
                 This is an  optional parameter  that if  used must  be
                 specified as *CHAR LEN(2).

   APY4PTY       The  run  time  priority assigned  to  the  APYRMTJRN4
                 batch  job.  A  value between  01 and 99  is returned.
                 This is an  optional parameter  that if  used must  be
                 specified as *CHAR LEN(2).

   APY5PTY       The  run  time priority  assigned  to  the  APYRMTJRN5
                 batch  job.  A  value between  01 and 99  is returned.
                 This  is an  optional parameter  that if  used must be
                 specified as *CHAR LEN(2).

   APY6PTY       The  run time  priority  assigned  to  the  APYRMTJRN6
                 batch job.   A  value between 01  and 99  is returned.
                 This  is an  optional parameter  that if used  must be
                 specified as *CHAR LEN(2).

   APY7PTY       The run  time  priority  assigned  to  the  APYRMTJRN7
                 batch job.   A  value between 01  and 99  is returned.
                 This  is an  optional parameter that  if used  must be
                 specified as *CHAR LEN(2).

   APY8PTY       The run  time  priority  assigned  to  the  APYRMTJRN8
                 batch job.   A value  between 01  and 99 is  returned.
                 This  is an optional  parameter that  if used  must be
                 specified as *CHAR LEN(2).

   APY9PTY       The  run  time  priority  assigned  to  the APYRMTJRN9
                 batch job.   A value  between 01  and 99 is  returned.
                 This  is an optional  parameter that  if used  must be
                 specified as *CHAR LEN(2).

   MSTTIMSLC     The  time  slice  assigned  to  the  master  APYRMTJRN
                 batch job.  A value  from 1 to 9,999,999  milliseconds
                 (9999.999 seconds) is  returned.  This is  an optional
                 parameter  that  if used  must be  specified  as *CHAR
                 LEN(7).

   MSTWAITTIM    The number  of  seconds  the master  job  should  wait
                 when there are  no more entries.   A number  between 1
                 and 999  is returned.   This is an  optional parameter
                 that if used must be specified as *CHAR LEN(3).

   APYWAITTIM    The  number  of  seconds the  apply  jobs  should wait
                 when there are  no more entries.   A number between  1
                 and 999  is returned.   This is an  optional parameter
                 that if used must be specified as *CHAR LEN(3).

   TSTLIB        The  name of the  test library (if any)  that is being
                 used  on   the  local   system  to   simulate   remote
                 journaling.   This is  an optional  parameter that  if
                 used must be specified as *CHAR LEN(10).

   CHKJOB        The  qualified  name  (job/user/jobnbr)  of the  Check
                 Job (APYRMTJRNC)  that  was  submitted.   This  is  an
                 optional parameter that  if used must be  specified as
                 *CHAR LEN(26).

TSTAPYRMT Command parameters                          *CMD
----------------------------

   NBRUPD        The  number of updates  to be  performed.   The number
                 of  updates  also determines  the  number of  adds and
                 deletes based  on a  percentage.   In  some cases  the
                 number you enter may be rounded up.

Restrictions
------------

See the section on 'Considerations'.

Prerequisites
-------------

The following TAA Tools must be on your system:

     CHGUSRSPC       Change user space
     CHKALLOBJ       Check *ALLOBJ special authority
     CHKOBJ2         Check object 2
     CHKOBJ3         Check object 3
     CLRDTAARA       Clear data area
     CLRDTAQ         Clear data queue
     CLRUSRSPC       Clear user space
     CMPDBF          Compare data base file
     CMPDTAARA       Compare data area
     CMPDTAQE        Compare data queue entry
     CPYBCKDTAQ      Copy back datq queue
     CRTDUPPF        Create duplicate PF
     CRTUSRSPC       Create user space
     CVTDAT          Convert date
     EDTVAR          Edit variable
     HLRMVMSG        HLL Remove message
     MOVCHRDEC       Move character to decimal
     RPGSTSDS        RPG status data structure
     RSNLSTMSG       Resend last message
     RTVDAT          Retrieve date
     RTVDBFA         Retrieve data base file attributes
     RTVDTAARAD      Retrieve data area description
     RTVDTAQD        Retrieve data queue description
     RTVMSGQA        Retrieve message queue attributes
     RTVSBMJOB       Retrieve submitted job
     RTVTIMSTM2      Retrieve time stamp 2
     RTVUSRSPC       Retrieve user space
     RTVSBSD         Retrieve subsystem description
     RTVSYSVAL3      Retrieve system value 3
     RTVUSRSPC       Retrieve user space
     RTVVALA         Retrieve value attributes
     UNADOPT         Unadopt authority
     SNDCOMPMSG      Send completion message
     SNDDIAGMSG      Send diagnostic message
     SNDDTAQ         Send data queue
     SNDESCMSG       Send escape message
     SNDSTSMSG       Send status message
     TAAARC          TAA Archive
     UPDPFILE        Update PF file

Implementation
--------------

None, the tool is ready to use.

Objects used by the tool
------------------------

   Object        Type    Attribute      Src member    Src file
   ------        ----    ---------      ----------    ----------

   STRAPYRMT     *CMD                   TAAJROD       QATTCMD
   SNDAPYRMTE    *CMD                   TAAJROD2      QATTCMD
   CRTAPYRMTD    *CMD                   TAAJROD3      QATTCMD
   DLTAPYRMTD    *CMD                   TAAJROD4      QATTCMD
   DSPAPYRMTD    *CMD                   TAAJROD5      QATTCMD
   CHGAPYRMT2    *CMD                   TAAJROD6      QATTCMD
   WRKAPYRMT     *CMD                   TAAJROD7      QATTCMD
   RTVAPYRMTD    *CMD                   TAAJROD8      QATTCMD
   ENDAPYRMT     *CMD                   TAAJROD9      QATTCMD
   CHGAPYRMTD    *CMD                   TAAJROD10     QATTCMD
   TSTAPYRMT     *CMD                   TAAJROD12     QATTCMD
   TAAJRODC      *PGM       CLP         TAAJRODC      QATTCL
   TAAJRODC2     *PGM       CLP         TAAJRODC2     QATTCL
   TAAJRODC3     *PGM       CLP         TAAJRODC3     QATTCL
   TAAJRODC4     *PGM       CLP         TAAJRODC4     QATTCL
   TAAJRODC5     *PGM       CLP         TAAJRODC5     QATTCL
   TAAJRODC6     *PGM       CLP         TAAJRODC6     QATTCL
   TAAJRODC7     *PGM       CLP         TAAJRODC7     QATTCL
   TAAJRODC8     *PGM       CLP         TAAJRODC8     QATTCL
   TAAJRODC9     *PGM       CLP         TAAJRODC9     QATTCL
   TAAJRODC10    *PGM       CLP         TAAJRODC10    QATTCL
   TAAJRODC12    *PGM       CLP         TAAJRODC12    QATTCL
   TAAJRODC24    *PGM       CLP         TAAJRODC24    QATTCL
   TAAJRODC27    *PGM       CLP         TAAJRODC27    QATTCL
   TAAJRODC31    *PGM       CLP         TAAJRODC31    QATTCL
   TAAJRODC32    *PGM       CLP         TAAJRODC32    QATTCL
   TAAJRODC35    *PGM       CLP         TAAJRODC35    QATTCL
   TAAJRODC41    *PGM       CLP         TAAJRODC41    QATTCL
   TAAJRODC42    *PGM       CLP         TAAJRODC42    QATTCL
   TAAJRODC43    *PGM       CLP         TAAJRODC43    QATTCL
   TAAJRODC44    *PGM       CLP         TAAJRODC44    QATTCL
   TAAJRODC45    *PGM       CLP         TAAJRODC45    QATTCL
   TAAJRODC46    *PGM       CLP         TAAJRODC46    QATTCL
   TAAJRODC47    *PGM       CLP         TAAJRODC47    QATTCL
   TAAJRODC49    *PGM       CLP         TAAJRODC49    QATTCL
   TAAJRODC54    *PGM       CLP         TAAJRODC54    QATTCL
   TAAJRODC55    *PGM       CLP         TAAJRODC55    QATTCL
   TAAJRODC56    *PGM       CLP         TAAJRODC56    QATTCL
   TAAJRODC59    *PGM       CLP         TAAJRODC59    QATTCL

Objects used by the tool - Continued
------------------------------------

   TAAJRODC61    *PGM       CLP         TAAJRODC61    QATTCL
   TAAJRODC62    *PGM       CLP         TAAJRODC62    QATTCL
   TAAJRODC81    *PGM       CLP         TAAJRODC81    QATTCL
   TAAJRODC82    *PGM       CLP         TAAJRODC82    QATTCL
   TAAJRODC83    *PGM       CLP         TAAJRODC83    QATTCL
   TAAJRODC89    *PGM       CLP         TAAJRODC89    QATTCL
   TAAJRODR7     *PGM       RPG         TAAJRODR7     QATTRPG
   TAAJRODR12    *PGM       RPG         TAAJRODR12    QATTRPG
   TAAJRODR41    *PGM       RPG         TAAJRODR41    QATTRPG
   TAAJRODR42    *PGM       RPG         TAAJRODR42    QATTRPG
   TAAJRODR43    *PGM       RPG         TAAJRODR43    QATTRPG
   TAAJRODR45    *PGM       RPG         TAAJRODR45    QATTRPG
   TAAJRODR48    *PGM       RPG         TAAJRODR48    QATTRPG
   TAAJRODR55    *PGM       RPGLE       TAAJRODR55    QATTRPG
   TAAJRODR61    *PGM       RPGLE
   TAAJRODR61    *MODULE    RPGLE       TAAJRODR61    QATTRPG
   TAAJRODR71    *MODULE    RPGLE       TAAJRODR71    QATTRPG
                            RPGLE       TAAJRODR72    QATTRPG
   TAAJRODR83    *PGM       RPG         TAAJRODR83    QATTRPG
   TAAJRODL      *FILE      LF          TAAJRODL      QATTRPG
   TAAJRODM      *FILE      PF          TAAJRODP      QATTRPG
   TAAJRODP      *FILE      PF          TAAJRODP      QATTRPG
   TAAJRODQ      *FILE      PF          TAAJRODQ      QATTRPG
   TAAJRODS      *FILE      PF          TAAJRODS      QATTRPG
   TAAJRODT      *FILE      PF          TAAJRODT      QATTRPG
   TAAJRODD      *FILE      DSPF        TAAJRODD      QATTRPG
   TAAJRODE      *FILE      DSPF        TAAJRODE      QATTRPG
   APYRMTJRN     *DTAARA

TAAJRODP is used as the model file when creating the APYRMTP file.

The TAAJRODM  file is  used as an  externally described  data structure
of the internal tables.

The  APYRMTJRN  *DTAARA is  for  use  with the  TAA  Productivity Tools
owner to assist when debugging is needed.

Structure
---------

STRAPYRMT   Cmd
   TAAJRODC   CL pgm - Submits TAAJRODC55 (Calls if *INTER2)
                         Adopts - Checks AUTL using UNADOPT
     TAAJRODC35    CL pgm Sbmtd by TAAJRODC - Checks active batch jobs
                         Adopts - Job is APYRMTJRNC
     TAAJRODC55    CLLE pgm Submitted or called from TAAJRODC
                         Adopts - Checks AUTL using UNADOPT
                         Starts *NEW activation group
       TAAJRODC54   CLLE Pgm - Check for recovery of previous use
                           Uses *CALLER activation group
                           Calls TAAJRODR61 if recovery is needed
       TAAJRODC56   CLLE Pgm - Creates user spaces and sbm TAAJRODR61
                                 for each required apply job
                           Uses *CALLER activation group
       TAAJRODR55   RPGLE Pgm - Master program - Extracts from JRNRCV
                           Uses *CALLER activation group
                           Submits TAAJRODR61 unless *INTER2 test
         TAAJRODC31   CLLE Pgm - Used for various commands (SNDPGMMSG)
                           Uses *CALLER activation group
       TAAJRODC59     CLP  Pgm  Submitted by TAAJRODC55 for *REFRESH
                            Adopts - Checks AUTL using UNADOPT
                              Does STRAPYRMT

   TAAJRODR61 - ILE  Pgm - Applies entries for the APYRMTJRNn job
                            Adopts
                            Starts *NEW activation group
     TAAJRODR61 - RPGLE Mod - Main function
       TAAJRODC61   CLLE Pgm - Sets run priority, returns values
                            Checks AUTL using UNADOPT
                            Uses *CALLER activation group
       TAAJRODC62   CLLE Pgm - Sends error messages during recovery
                            Uses *CALLER activation group
       TAAJRODC32   CLLE Pgm - Performs CL functions
                            Uses *CALLER activation group
     TAAJRODR71 - RPGLE Mod - Interface to C file routines
       TAAJRODR72 - RPGLE Copy routines for TAAJRODR71

                    The TAAJRODR61 structure is  submitted for each  of
                    the APYRMTJRNn jobs.

Structure - Continued
---------------------

SNDAPYRMTE  Cmd
   TAAJRODC2   CL pgm

CRTAPYRMTD  Cmd
   TAAJRODC3   CL pgm
     TAAJRODC24  CL Pgm

DLTAPYRMTD  Cmd
   TAAJRODC4   CL pgm

DSPAPYRMTD  Cmd
   TAAJRODC5   CL pgm
     TAAJRODD    DSP file

CHGAPYRMTD  Cmd
   TAAJRODC10  CL pgm

CHGAPYRMT2  Cmd
   TAAJRODC6   CL pgm
     TAAJRODC24  CL Pgm

WRKAPYRMT   Cmd
   TAAJRODC7   CL pgm
     TAAJRODR7   RPG pgm
       TAAJRODE    DSP file
       TAAJRODC27  CL pgm

RTVAPYRMTD  Cmd
   TAAJRODC8   CL pgm

ENDAPYRMT   Cmd
   TAAJRODC9   CL pgm

TSTAPYRMT   Cmd
   TAAJRODC12  CL pgm
     TAAJRODR12  RPG pgm

Structure - Continued
---------------------

Test on local system with simulated library

   TAAJRODC41   CL Pgm Create libraries (TAATSTRMT and TAATSTSIM)
     TAAJRODR41    RPG Pgm to add records to FILEA
   TAAJRODC42    CL Pgm Update objects
     TAAJRODR42    RPG Pgm Update objects
     TAAJRODR48    RPG Pgm Update objects using commit
   TAAJRODC43    Compare results
   TAAJRODC49    Delete libraries

Additional volume test programs

   TAAJRODC44    Creates n TSTFnnn files in both libraries
                    eg CALL TAAJRODC44 PARM('010') creates 10 files
   TAAJRODC45    Writes n records to the TSTFnnn files
     TAAJRODR45    RPG to write to TSTFnnn files
                    eg CALL TAAJRODC45 PARM('00050') writes 40 records

Test using both local and remote system

   TAAJRODC81     Create local library TAATSTRMT and objects
   TAAJRODC82     Create remote library TAATSTRMT and objects
   TAAJRODC83     Update objects in local library
     TAAJRODR83     Update objects in local library
   TAAJRODC89     Delete local test library

Added to TAA Productivity tools December 15, 2002

Home Page

Up to Top