TAA Tools
APYRMTJRN       APPLY REMOTE JOURNAL                   TAAJROD

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

            CALL           PGM(QCMD)

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

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

            EDTLIBL

       If the TAATOOL library does not exist, add it:

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

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

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

             CALL      PGM(TAAJRODC49)

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

             CALL      PGM(TAAJRODC41)

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

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

              Display the 'local' library with:

                    DSPLIB        LIB(TAATSTLCL)

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

                    RCV0001    *JRNRCV
                    JRN1       *JRN

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

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

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

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

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

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

              Display the simulated 'remote' library with:

                   DSPLIB        LIB(TAATSTSIM)

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

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

              Display the APYRMTJRN library:

                  DSPLIB     LIB(APYRMTJRN)

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

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

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

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

             CALL          PGM(TAAJRODC42)

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

  5.   Use WRKSBS to display the active subsystems:

             WRKSBS

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

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

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

       Use F3 to exit the WRKSBS display.

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

       The *DTAARA objects have changed in value.

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

       The data base files have been changed

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

  7.   Compare the objects and their data by entering:

             CALL      PGM(TAAJRODC43)

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

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

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

             DSPJRN    JRN(TAATSTLCL/JRN1)

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

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

             ENDAPYRMT

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

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

             WRKSBS

  12.  Review the spooled files created by each job.

             WRKSPLF

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

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

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

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

             WRKAPYRMT

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

         --   Option 5 lets you review the detail information.

         --   Option 2 lets you change the default options:

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

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

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

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

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

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

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

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

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

             DSPAPYRMTD

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

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

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

             CHGAPYRMTD

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

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

             STRAPYRMT    APYRMTLIB(APYRMTJRN) TSTLIB(TAATSTSIM)

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

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

       For example, you could do the following:

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

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

             EDTDBF        FILE(TAATSTLCL/FILEA) MBR(xxx)


       You can check the results manually by using:

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

       Or you can check the results with the program:

             CALL          PGM(TAAJRODC43)

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

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

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

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

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

             CALL          PGM(TAAJRODC44) PARM('100')

       The files will be named TSTF001 - TSTF100.

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

             CALL          PGM(TAAJRODC45) PARM('00200')

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

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

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

             ENDAPYRMT

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

             CALL      PGM(TAAJRODC49)

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

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

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

            EDTLIBL

       If the TAATOOL library does not exist, add it:

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

             DSPLIB      LIB(TAATSTRMT)

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

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

             CALL        PGM(TAAJRODC81)

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

             DSPLIB      LIB(TAATSTRMT)

       You should see:

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

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

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

       Enter the command:

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

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

             DSPLIB      LIB(APYRMTJRN)

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

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

             CALL        PGM(TAAJRODC82)

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

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

             DSPLIB      LIB(TAATSTRMT)

       You should see:

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

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

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

             WRKRDBDIRE

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

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

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

  10.  On the 'remote' system, enter:

             DSPLIB        LIB(TAATSTRMT)

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

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

       On the 'local' system, enter:

             CHKRMTJRN    SRCJRN(TAATSTRMT/JRN1)

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

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

             WRKJRNA      JRN(TAATSTRMT/JRN1)

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

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

             DSPLIB        LIB(TAATSTRMT)

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

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

            DSPJRN         JRN(TAATSTRMT/JRN1)

       You should see the entries:

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

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

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

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

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

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

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

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

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

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

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

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

             DSPLIB        LIB(APYRMTJRN)

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

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

             STRAPYRMT

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

             WRKSBS

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

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

             CALL          PGM(TAAJRODC83)

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

             WRKSPLF

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

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

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

             PRTDB2       FILE(TAATSTRMT/TSTFILE)

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

             DSPDTAARA    DTAARA(TAATSTRMT/DTAARA1)

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

             DSPDTAQ      DTAQ(TAATSTRMT/DTQ1)

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

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

            DSPJRN       JRN(TAATSTRMT/JRN1)

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

             ENDAPYRMT

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

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

             WRKSPLF

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

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

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

            WRKAPYRMT

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

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

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

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

             CALL      PGM(TAAJRODC46)

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

             CALL      PGM(TAAJRODC47)

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

             TSTAPYRMT   NBRUPD(50)

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

  34.  Start the apply function on the remote system.

                    STRAPYRMT

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

            DSPMBRD    FILE(TAATSTRMT/TSTAPYRMT)

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

  36.  End the test with:

           ENDAPYRMT

  37.  Start the apply remote process again with:

                    STRAPYRMT

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

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

             TSTAPYRMT   NBRUPD(nnnnn)

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

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

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

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

            CHKRMTJRN    JRN(TAATSTRMT/JRN1)

       You should see that the remote journal is not active.

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

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

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

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

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

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

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

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

                    STRAPYRMT

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

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

              On the 'local' system, change the objects.

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

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

              Check the results with:

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

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

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

             ENDAPYRMT

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

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

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

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

            WRKJRNA        JRN(TAATSTRMT/JRN1)

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

  2.   Use F3 to exit the WRKJRNA display.

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

            RMVRMTJRN      RDB(xxx) SRCJRN(TAATSTRMT/JRN1)

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

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

            CALL           PGM(TAAJRODC89)

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

            DLTLIB         LIB(TAATSTRMT)

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

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

            DLTLIB         LIB(APYRMTJRN)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The following objects are created:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   DSPAPYRMTD    Displays the  attributes of the APYRMTJRN  user space.

   DLTAPYRMTD    Deletes   the  objects   created  by   the  CRTAPYRMTD
                 command.

   RTVAPYRMTD    Retrieves the attributes  of a APYRMTJRN  description.

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

Run time commands

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

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

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

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

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

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

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

       You must be authorized to TAAAPYRMT to do the following:

              CRTAPYRMTD
              STRAPYRMT
              ENDAPYRMT
              SNDAPYRMTE

       The following commands are public:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

The following data base entries are processed:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

             SNDAPYRMTE   JRN(xxx) OPTION(*SHUTDOWN)

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

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

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

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

See the SNDAPYRMTE command for specific details about each option.

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

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

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

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

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

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

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

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

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

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

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

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

  **   A duplicate key error has occurred.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

             DSPAPYRMTD

Ensure that the message queue described is in break mode.

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

       On the 'remote' system, create a file:

             CRTPF         FILE(TAATSTRMT/FILEX) RCDLEN(50)

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

             CRTPF         FILE(TAATSTRMT/FILEX) RCDLEN(50)

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

             EDTDBF        FILE(TAATSTRMT/FILEX)

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

       On the 'local' system, start journaling with:

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

       On the 'local' system, use EDTDBF again:

             EDTDBF        FILE(TAATSTRMT/FILEX)

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

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

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

             PRTDB2        FILE(TAATSTRMT/FILEX)

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

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

       On the 'local' system, create a file:

             CRTPF         FILE(TAATSTRMT/FILEY) RCDLEN(50)

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

             CRTPF         FILE(TAATSTRMT/FILEY) RCDLEN(45)

       On the 'local' system, start journaling with:

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

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

             EDTDBF        FILE(TAATSTRMT/FILEX)

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

  **   To simulate a missing object:

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

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

       On the 'local' system, start journaling with:

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

       On the 'local' system, change the data area

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

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

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

There are several functions that need to be considered:

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

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

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

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

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

       You should ensure that no errors were found.

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

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

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

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

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

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

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

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

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

            ENDAPYRMT

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

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

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

            WRKJRNA    JRN(xxx/yyy)

       Use F15 to display the journal receivers.

       Delete all but the currently attached journal.

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

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

            WRKJRNA    JRN(xxx/yyy)

       Use F15 to display the journal receivers.

       Delete all but the currently attached journal.

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

            WRKJRNA    JRN(xxx/yyy)

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

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

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

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

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

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

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

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

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

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

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

RGZPFM
------

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

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

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

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

See the section on 'Significant object changes'.

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

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

See the section on 'Significant object changes'.

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

The following describes some typical situations and solutions:

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

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

  **   RNMOBJ or MOVOBJ is required.

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

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

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

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

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

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

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

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

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

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

The following describes these approaches:

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

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

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

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

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

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

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

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

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

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

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

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

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

            SNDAPYRMTE    JRN(xxx) OPTION(*TIMSTM)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

There are two considerations:

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

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

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

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

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

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

The system supports two methods of activating the remote journal:

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

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

             CHGRMTJRN    JRNSTATE(*ACTIVE)

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

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

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

Most recovery is handled automatically.  For example,

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

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

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

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

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

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

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

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

            ENDAPYRMT

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

            DSPJRN     JRN(xxx/yyy)

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

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

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

       The first entry processed should be what you requested.

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

APYRMTJRN is limited to the data portion of:

      - Data Base members
      - Data Areas
      - Data Queues

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

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

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

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

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

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

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

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

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

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

       Data record changes - Journal code = R

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

       Member changes - Journal code = F

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

       Data Area changes - Journal code = E

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

       Data Queue changes - Journal code = Q

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

     SNDAPYRMTE changes - Journal type = U

         TT = Option types

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

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

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

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

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

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

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

             STRJRNLIB     LIB(xxx) JRN(yyy)

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

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

             STRJRNLIB     LIB(xxx) JRN(yyy)

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

             WRKJRNLIB     LIB(xxx) JRNOPT(*xxx)

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

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

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

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

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

The basic steps are:

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

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

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

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

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

       A typical command would be:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

To compare the data consider:

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

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

   Data Area     The TAA CMPDTAARA command may be used.

   Data Queue    The TAA CMPDTAQE command may be used.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

A few commands send unique escape messages:

      STRAPYRMT   TAA9891    Sequence number not found.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

                 *CHANGE or *EXCLUDE may be entered.

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

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

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

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

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

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

                 A   specific  journal  receiver  and  library  may  be
                 entered.

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

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

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

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

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

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

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

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

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

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

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

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

                 The  option   requested  will  occur  on   the  remote
                 system.

   OPTION        The option to be taken.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

See the section on 'Considerations'.

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

The following TAA Tools must be on your system:

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

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

None, the tool is ready to use.

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

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

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

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

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

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

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

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

Structure
---------

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

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

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

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

SNDAPYRMTE  Cmd
   TAAJRODC2   CL pgm

CRTAPYRMTD  Cmd
   TAAJRODC3   CL pgm
     TAAJRODC24  CL Pgm

DLTAPYRMTD  Cmd
   TAAJRODC4   CL pgm

DSPAPYRMTD  Cmd
   TAAJRODC5   CL pgm
     TAAJRODD    DSP file

CHGAPYRMTD  Cmd
   TAAJRODC10  CL pgm

CHGAPYRMT2  Cmd
   TAAJRODC6   CL pgm
     TAAJRODC24  CL Pgm

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

RTVAPYRMTD  Cmd
   TAAJRODC8   CL pgm

ENDAPYRMT   Cmd
   TAAJRODC9   CL pgm

TSTAPYRMT   Cmd
   TAAJRODC12  CL pgm
     TAAJRODR12  RPG pgm

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

Test on local system with simulated library

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

Additional volume test programs

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

Test using both local and remote system

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

Added to TAA Productivity tools December 15, 2002


Home Page Up to Top