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, delete it using DLTLIB.
6. On the 'remote' system, ensure library TAATSTRMT does not
exist by entering.
DSPLIB LIB(TAATSTRMT)
If the library exists, use DLTLIB (you may have to respond 'I'
to ignore the message that the journal receiver has not been
saved).
7. 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.
8. 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.
9. 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'.
10. 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')
11. On the 'remote' system, enter:
DSPLIB LIB(TAATSTRMT)
You should see that the system has created the JRN1 journal
for you.
12. 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.
13. 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').
14. 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.
15. 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.
16. On the 'remote' system, create the library needed for the TAA
APYRMTJRN function:
CRTLIB LIB(APYRMTJRN)
TEXT('Used by TAA APYRMTJRN tool')
17. 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.
18. On the 'remote' system, create the objects needed for the TAA
APYRMTJRN function:
CRTAPYRMTD JRN(TAATSTRMT/JRN1)
MSGQ(APYRMTJRN/TSTMSGQ)
19. 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'.
20. On the 'remote' system, start the TAA APYRMTJRN function with
the command:
STRAPYRMT
21. 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.
22. 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)
23. 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.
24. 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.
25. On both the 'local' and 'remote' systems compare the data base
file using:
PRTDB2 FILE(TAATSTRMT/TSTFILE)
26. On both the 'local' and 'remote' systems compare the data area
using:
DSPDTAARA DTAARA(TAATSTRMT/DTAARA1)
27. 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 a 'receive' entries. The test program
sent two data queue entries and then received the first entry.
Therefore, only the second entry still exists.
28. On the 'remote' system, to review the journal entries, enter:
DSPJRN JRN(TAATSTRMT/JRN1)
29. On the 'remote' system, end the APYRMTJRN function by
entering:
ENDAPYRMT
You should see a break message that the APYRMTJRN function is
ending.
30. 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.
31. 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.
32. For a volume test, do the following on the 'local' system to
create the TSTAPYRMT file and start journaling.
CALL PGM(TAAJRODC46)
33. On the remote system, create the same file with:
CALL PGM(TAAJRODC47)
34. 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.
35. Start the apply function on the remote system.
STRAPYRMT
36. 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).
37. End the test with:
ENDAPYRMT
38. 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.
39. Use TSTAPYRMT again and specify as large a number as desired:
TSTAPYRMT NBRUPD(nnnnn)
40. When the records have been applied, use DSPMBRD as previous to
determine if the same number of records exist.
41. You can run as many tests as required with TSTAPYRMT. You can
try some of the SNDAPYRMTE options such as *SHUTDOWN, *CPY,
etc.
42. 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.
43. When finished, use ENDAPYRMT to end the apply and review the
spooled files that are output.
44. 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'.
45. On the 'remote' system, to end the function, enter:
ENDAPYRMT
You should see a break message describing that the APYRMTJRN
function has ended.
46. 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
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.
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
|
