TAA Tools
APYUSRCHG       APPLY USER JOURNAL CHANGES             TAAJRNG

The Apply User Journal  Changes command is an alternative  to the i5/OS
supplied APYJRNCHG command.

APYJRNCHG is very strict in what it allows:

  **   The  file  being applied  to  must  be the  same  file that  was
       journaled.  You cannot apply to a duplicate of the file.

  **   If  a file is restored, the  file must have been being journaled
       when it was saved.

When a file  is journaled, a  special internal identification is  used.
The internal ID  of the file and the journal entry  must match to allow
the  apply to take  place.   The system ensures  that the  unique ID is
used only once per system.  Therefore:

  **   You cannot  save  the file  being  journaled,  restore it  to  a
       different library  on the  same system  and expect  APYJRNCHG to
       work successfully to the duplicate file.

  **   It  is  possible  to transport  the  journal  receiver from  one
       system  to  another   and  apply  the   journal  changes   using
       APYJRNCHG.   This requires  that the  original file be  restored
       on the  second system so that  the internal ID is  the same when
       the  apply  occurs.    The  Programmers  Guide  has  a  detailed
       explanation.

The TAA  tool  APYUSRCHG works  with converted  journal  entries.   The
conversion  to a  data base  file must  be done  by the  DSPJRN command
using  OUTFILFMT(*TYPE1).  Once the  conversion has occurred, APYUSRCHG
will allow  you to  apply journal  changes to  the original  file or  a
duplicate  file.   Several internal  checks  are made  to help  provide
integrity  (see   later  discussion),  but  in   general  you  can  use
APYUSRCHG and  bypass the  major restrictions  of the  system  supplied
command.

To use  APYUSRCHG,  you must  first convert  the journal  entries to  a
data  base  file  using the  DSPJRN  command.    DSPJRN  allows you  to
control  what  file/entries  you  want  to  be  converted,  the journal
receivers to be used, the journal entry to start at etc.

                       *****************
                       *               *
                       *   Journal     *
                       *   Receiver    *
                       *               *
                       *****************
                              *
                              *
                           DSPJRN   ....... ENTDTALEN(xxx)
                              *
                              *
                        DSPJRN OUTFILE
    *************************************************************
    *   125 Bytes         *  Nbr of bytes per ENTDTALEN parm    *
    *  Standard fields    ***************************************
    *   eg File, member,  *                           *         *
    *     RR number ...   *    Physical record image  *         *
    *************************************************************

A typical command would  be to convert all  of the journal entries  for
the current journal receiver such as:

      DSPJRN      JRN(JOURNAL(X) ENTDTALEN(500) JRNCDE(R)
                     OUTPUT(*OUTFILE) OUTFILE(LIB1/JRNOUTP)

The ENTDTALEN  parameter is  very important.   It must be  specified to
hold  the largest physical record being journaled.   If it is less than
the largest  physical record  length, the  APYUSRCHG  command will  not
apply changes for that file.

The use  of JRNCDE(R)  only converts the  'record' entries  that appear
in  the  journal.   These are  the  only journal  entries  processed by
APYUSRCHG.    If  other  entries  exist,  they  will  be  bypassed   by
APYUSRCHG.   See  the  later discussion  on  the specific  entry  types
processed.

A typical command to apply all of the changes would be:

      APYUSRCHG   DSPJRNOUT(JRNOUTP)

A  report is printed  to QPRINT which  describes the number  of entries
applied  for each file/member.   If an error has  occurred on a member,
the problem  is identified.   No further  updates to  that member  will
occur.

Because  the records  are  sorted  by relative  record  number (not  by
date), the function is year 2000 ready.

Applying the changes to a duplicate file
----------------------------------------

APYUSRCHG  will allow  you  to apply  the changes  from  one file  to a
duplicate of the file.   Normally you would  create the duplicate  with
CRTDUPOBJ  or  a  restore  to  a   different  library  (See  the  later
discussion).

Only one  file can be applied  per use of APYUSRCHG  when applying to a
duplicate file.  A typical command to do this would be:

      APYUSRCHG   DSPJRNOUT(JRNOUTP) JRNLDFILE(LIB1/FILEA)
                     TOFILE(LIB1/FILEA2)

APYUSRCHG typical uses
----------------------

  **   Assume you  started  journaling  and forgot  to  save  the  file
       after journaling was  started.  If  the file is restored  from a
       saved version  that occurred before journaling  was started, the
       APYJRNCHG command cannot be used.  APYUSRCHG could be used.

  **   Assume  you have a file that must  be online for update 24 hours
       a day during the week.   It cannot be backed up during  the week
       because the file  is always open for update and  you do not want
       to  use the  system SAVWHLACT  function.   Assume you  have many
       journal changes.   If you backup  the file on  the weekend,  the
       recovery  time  to  restore  the  last  backup  and  apply  many
       changes could be significant.

  **   APYUSRCHG can  be used to minimize the  recovery time.  A second
       file would be created on the  same system which is a  duplicate.
       This must  be done  while the first  file is  static (no  one is
       updating   it)  so   that  the   relative  record   numbers  are
       synchronized  (CRTDUPOBJ  would be  a good  choice).   You would
       apply the  journal  changes to  the  duplicate using  APYUSRCHG.
       Assume you  apply all of  the days changes  once or twice  a day
       and then save the duplicate file at night.

       With  this technique,  if the  file needs  to be  recovered, you
       only need  to apply the  last set  of changes  to the  duplicate
       with  APYUSRCHG and  then  use CPYF  or  MOVOBJ  to replace  the
       original file.

  **   Assume you  have a file that must be  online for update 24 hours
       a day and  7 days a  week.  The  file cannot  ever be backed  up
       because some user  always has the  file open for update  and you
       do not want to use the system 'Save While Active' function.

       APYUSRCHG can  be used to keep a duplicate  file on line so that
       in the event recovery is needed, it is possible.

       A  second file would  be created on  the same system  which is a
       duplicate of  the first.   This  must  be done  while the  first
       file  is  static (no  one  is  updating)  so that  the  relative
       record  numbers are synchronized  (CRTDUPOBJ is  a good choice).
       You would  apply  the journal  changes  to the  duplicate  using
       APYUSRCHG.   Assume you apply  all of  the days changes  once or
       twice a day and then save the duplicate file at night.

       With  this technique,  if the  file needs  to be  recovered, you
       only need to  apply the  last set  of changes  to the  duplicate
       with  APYUSRCHG and  then  use CPYF  or  MOVOBJ to  replace  the
       original file.

       Note  that the system  does not  support the capability  to have
       the  application available all  of the time.   There are several
       conditions  that  require   either  a  dedicated   system  (e.g.
       SAVSYS),  a  re-IPL  (reset  the  address counters)  or  a  down
       period (e.g.  installing a new release).

  **   Assume  you  are journaling  many  files on  your  system and/or
       using access  path journaling.   You  want to  duplicate one  or
       more of the journaled  files on other systems.   To do this, you
       need  to take  the journal  changes from  your system  and apply
       them on other systems.

       You can transmit  a journal  receiver from  your central  system
       to the remote  systems, but the receiver probably  contains many
       entries for  files or access  path changes that you  do not want
       to  transmit.   If  you are  using  access path  journaling, the
       receiver can be very large.

       You can extract  the entries for  the files you want  duplicated
       on other  systems with DSPJRN.   The smaller file  would then be
       transmitted  to  the  other systems  and  APYUSRCHG  used.   You
       might   also   consider    summarizing   the   entries    before
       transmission (See the TAA tool SUMJRNENT).

Entry types processed
---------------------

APYUSRCHG will only  process the JOCODE =  R type journal entries.   If
other entries exist, they will be bypassed.

For  'R' type,  the typical  entries of  PT (Add),  UP (Update)  and DL
(Delete) are processed.

Also processed are:

   DR            Delete  rollback.    If   you  are  using   commitment
                 control,  this  entry  will  appear  if  you  added  a
                 record  and then a  rollback occurred.   These entries
                 are treated as DL types.

   UR            Update   rollback.    If   you  are  using  commitment
                 control, this  entry  will appear  if  you updated  or
                 deleted a  record and then  a rollback occurred.   The
                 entry  contains  the  record image  that  must  be put
                 back into the  data base.   APYUSRCHG will treat  this
                 as a  UP type if  the record exists  and as a  PX type
                 if the record does not exist.

   PX            Put  direct.  This entry  will appear if  you write to
                 a specific relative record  number rather than add  at
                 the end of  the file.   Both COBOL and RPG  can create
                 this  type  of entry.    RPG requires  that  the RECNO
                 file  continuation  function  be  used.    When  PX is
                 used, it  normally  means that  you have  used  INZPFM
                 and  initialized  the  file  to a  number  of  deleted
                 records.     To  properly  handle  this  record  type,
                 special handling is used by APYUSRCHG.

The UP = Update  Before journal entry  caused by commitment control  is
bypassed by APYUSRCHG.

Making a duplicate of a file
----------------------------

If you are making  a duplicate of a file and using  APYUSRCHG, you must
be  sensitive to the relative  record numbers if  deleted records exist
in the  file.    Any  SAV  command  and  CRTDUPOBJ  will  maintain  the
existing relative record numbers.

If the duplicate file is  on the same system as the  original file, you
may  need to  copy  the duplicate  back  to the  original  for recovery
purposes.

CPYF  requires two  parameters be  specified to  duplicate a  file with
the same relative record numbers.

  **   FROMRCD(1).    This  ensures  that  even  if  a  keyed  file  is
       specified that the copy will be in arrival sequence order.

  **   COMPRESS(*NO).    The  default  for  CPYF  is  to  compress  out
       deleted  records.  Specifying *NO causes  the deleted records to
       be copied.

Checking performed by APYUSRCHG
-------------------------------

To prevent errors being caused  by APYUSRCHG, several integrity  checks
are performed:

  **   The  length of  the 'entry  data  length' in  the journal  entry
       must  match the  length of the  file being  applied to.   If you
       have changed  the file  format  (so it  is longer  or  shorter),
       this  will prevent  the  apply.   If  you  did not  specify  the
       ENTDTALEN  value correctly on  DSPJRN (e.g.   you did  not allow
       enough  room  for the  physical  record image),  this  will also
       prevent the apply.

  **   If an  update  or  delete  journal entry  exists,  the  relative
       record number of the record must exist in the file.

  **   If  an  add  (PT)  journal  entry exists,  the  relative  record
       number  of the  record must not  exist.   Additions always occur
       at the end of the file.   After adding the record, the  relative
       record  (RR) number  of the  journal entry  is compared  against
       the   RR  number  of   the  record  added   (the  file  feedback
       information is used).   If  they differ, an  exception is  noted
       and no more updates occur to the member.

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

To provide  good  performance for  APYUSRCHG, the  journal entries  are
sorted by  relative record number within each member.   This allows the
member  to be  opened only  once per use  of APYUSRCHG.   If  an add or
delete  journal   entry  exists,   the   data  base   change  is   made
immediately.   All update  entries are read  in sequence, but  only the
last  update (it contains the full record  image) is used to update the
data base.

Sorting  the  records  in  relative   record  number  order  not   only
minimizes  the  number of  opens  and  updates,  but also  causes  less
random disk arm movement to process thru the file.

APYUSRCHG is  written to handle up  to 2000 byte record  lengths.  If a
record size exceeds this, you  can change the code  to handle it.   The
2000  limit allows  most  records  to  be handled  properly  and  still
provides  reasonable performance.    See the  later section  on  how to
change the program to handle larger values if needed.

One  of  the  major  factors that  influences  the  performance  of the
APYJRNCHG command  is the average  number of  access path changes  that
each entry  causes.  If you tend  to have several updates  for the same
relative  record and  each update  causes several access  path changes,
the advantage of accumulating the  updates can be very significant  for
APYUSRCHG versus APYJRNCHG.

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

   DSPJRNOUT     The  qualified name  of the  data base  file that  was
                 specified  as   the  output  file  for  DSPJRN.    The
                 library defaults to *LIBL.

   JRNLDFILE     The qualified  name of  the data  base file  that  was
                 journaled.  The  default is *ALL.  Normally,  you will
                 want to  use DSPJRN to subset the  files that you want
                 to  apply to.  However,  if you already have converted
                 the journal  entries with  DSPJRN, you  can apply  one
                 file at a time with APYUSRCHG.

                 Note that if  you use a specific file  name, you enter
                 the  name   of  the  file  that  was  journaled.    By
                 default, this is  the file  that will  be applied  to.
                 If you  want to  apply to  a duplicate  file, see  the
                 TOFILE parameter.

   JRNLDMBR      The  member of the  JRNLDFILE to  be applied to.   The
                 default  is   *ALL.     If  an   individual  file   is
                 specified,  either  all  members  of  the  file  or  a
                 specific  member  will be  applied  to.   *ALL  may be
                 used if the file has only a single member.

   TOFILE        The   file  to  be   applied  to.     The  default  is
                 *JRNLDFILE.  Specifying a  file allows you to use  the
                 journal  entries that  occurred  from one  file to  be
                 applied  to a  duplicate file.   If  a file  is named,
                 JRNLDFILE cannot be *ALL.

                 Only a single  file can be  named, therefore each  use
                 of applying  to a  duplicate file requires  a separate
                 APYUSRCHG command to be run.

   TOMBR         The  member  to   be  applied  to.    The  default  is
                 *JRNLDMBR.    If  a   specific  entry  is  used,   the
                 JRNLDFILE parameter cannot be *ALL.

                 If you are  applying to a  duplicate file, one  or all
                 members can  be applied to in a  single execution of a
                 APYUSRCHG  command.    The default  of  *JRNLDMBR when
                 JRNLDMBR(*ALL) is  specified may be  used if the  file
                 has only a single member.

   SORTED        A *YES/*NO  value that defaults to *NO.   The Reformat
                 Utility  is  used  to  sort  the  journal  entries  to
                 minimize the number  of updates  (if multiple  updates
                 to the same  RR number have occurred)  and to minimize
                 disk  arm movement.   If you  have already  sorted the
                 entries, you  can  bypass  this step.    The  sequence
                 that  the  entries  should be  sorted  is  (the  field
                 names  refer  to  the  values  in  the  DSPJRN  output
                 format):

                     JOLIB
                       JOOBJ
                         JOMBR
                           JOCTRR

                 Since   the   Reformat   Utility   defaults   to  sort
                 duplicates  in   arrival   sequence  order,   multiple
                 updates  to the same  RR number  will be  in sequence.
                 If  you   sort  the  records,  you  must  ensure  this
                 sequence.

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

  **   The file  and  member  to be  applied  to  must exist.    It  is
       possible  to apply  to  a duplicate  file  without the  original
       file or member existing.

  **   A  physical file  may not  exceed 2000  bytes in  record length.
       If you have files  that exceed this length,  you can change  the
       program to allow for it.  See the later section.

  **   APYUSRCHG only  does  a forward  apply.   It cannot  be used  to
       'back down'  the data base  such as with  the RMVJRNCHG command.

  **   Just   like   the  APYJRNCHG   command,  APYUSRCHG   is  totally
       dependent on consistent  relative record numbers  to apply.   If
       you reorganize  the file or  copy it without  COMPRESS(*NO), the
       relative  record numbers  are likely  to change.   Although some
       logical errors will be found  by APYUSRCHG, you must be  careful
       in how you are performing the apply.

       The  APYJRNCHG  command  prevents  the  apply  from  crossing  a
       boundary  such as  RGZPFM.   APYUSRCHG assumes  that you  are in
       control of when RGZPFM, CLRPFM  or INZPFM have occurred and  are
       working with the  proper set of  journal entries to  be applied.

       If  the file was  initialized to  deleted records,  the recovery
       steps  should do  the same  initialization function.   Normally,
       these  means that  the  file  should  be  restored  from  backup
       media.

Handling larger than 2000 byte records
--------------------------------------

To  provide   better  performance,  APYUSRCHG  is   written  to  handle
physical  record lengths  up to  2000 bytes.   The  following describes
the changes needed to increase the size.

  **   At  about  statement   2.00,  3.00   and  8.00   are  the   file
       descriptions.   The record  size is  2125.   Each journal  entry
       has  125 bytes of heading  information.  If  your largest record
       length is 5000 bytes, change the '2125' values to 5125.

  **   At about statement 35.00 is  the input field description of  the
       JOESD field.   This is the  length of your largest  data record.
       The  'from  position; should  remain  126.    The 'to  position'
       should  be changed.  If your  largest record size is 5000 bytes,
       change the '2125' value to 5125.

  **   At about  statement  46.00 is  the JOESD  field  described as  a
       data   structure  to   avoid  the   RPG  maximum   field  length
       restriction.   If  your  largest record  length is  5000, change
       the '2000' value to 5000.

  **   At about  statement  110.00  is  the test  to  ensure  that  the
       program is not  being requested to update a  record greater than
       the  maximum record length  specified in  the program.   If your
       largest record  length  is  5000, change  the  '2000'  value  to
       5000.

  **   At about  statements 358.00,  360.00 and  362.00 are the  output
       locations for  the field JOESD.   If your  largest record length
       is 5000, change the '2000' values to 5000.

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

Normal  security is used.   The user  of the APYUSRCHG  command must be
authorized to make changes to each of the files to be applied to.

You  may want  to  control  who  is authorized  to  use  APYUSRCHG  and
prevent public use of the command.

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

The following TAA Tool must be on your system:

     SNDCOMPMSG   Send completion message
     SNDESCMSG    Send escape message
     SNDSTSMSG    Send status message
     SORTDB       Sort data base

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

The tool is ready to use.

See  the  previous discussion  on  the use  of  DSPJRN  to convert  the
journal receiver entries so they can be processed by APYUSRCHG.

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

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

   APYUSRCHG     *CMD                       TAAJRNG       QATTCMD
   TAAJRNGC      *PGM           CLP         TAAJRNGC      QATTCL
   TAAJRNGR      *PGM           RPG         TAAJRNGR      QATTRPG
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top