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

Last modified on March 10, 2014 © 1995, 2014 - TAA Tools, Inc.