TAA Tools
MTNJRN          MAINTAIN JOURNAL                       TAAJRNC

The  Maintain Journal  command  provides for  changing  to new  journal
receivers  and  cleaning  up   old  journal  receivers.    The  command
supports  either a specific  journal name or  *ALLSTD which handles the
following system standard  journals (A special  value name may also  be
used for each of the journals):

        Journal               Special value
        -------               -------------

        QAOSDIAJRN            *OFFICE
        QDSNX                 *DSNX
        QSNADS                *SNADS
        QSXJRN                *PROB
        QZMF                  *MAIL

The journals are either:

  **   An  integral  part of  the  system  support  and/or recovery  of
       system objects.

  **   Provide for an audit trail of occurrences.

See  the  later  discussion on  the  recovery aspects  of  each  of the
journals.

Note  that  the  optional  system  journals  for  job  accounting   and
auditing (QACGJRN  and QAUDJRN)  are not  included in  the list.   They
can be specified individually.

Other  standard journals  supplied by  the system  such as  QLZALOG and
QMAJRN are not supported because they receive little activity.

The proper sequence of events is normally to:

   - Change to a new receiver
   - Backup the old receiver and the journaled objects
   - Delete the receivers no longer needed online

Because of this, the MTNJRN  command with the JRN(*ALLSTD) function  is
normally issued as  part of a save  of the QUSRSYS and  QDOC libraries.
For example, a typical strategy would be:

  **   Weekly.  Full backup and cleanup journaling.

       Typical commands would be:

             MTNJRN    JRN(*ALLSTD) GENNEWRCVR(*YES)
             SAVLIB    QUSRSYS ....
             SAVDLO    ....
             MTNJRN    JRN(*ALLSTD) DLTOLDRCVR(*YES) RETAINDAYS(0)

       An  alternative is  to use  the system  supplied menu  option to
       backup the entire system instead of the two save commands.

  **   Daily.     Save  the  changed  objects  (including  the  journal
       receivers)  in  QUSRSYS  using  SAVCHGOBJ.    Save  the  changed
       documents and folders in QDOC using SAVDLO.

You  can also  use the  MTNJRN  command in  your own  save strategy  or
independently of saving the journal receivers.

MTNJRN is a slow running command and should be submitted to batch.

If  you attempt to delete  a journal receiver without  saving it first,
the system  will provide an  inquiry message  that informs  you of  the
condition and  allows an  I=Ignore or C=Cancel  response.   The default
for  MTNJRN is  to allow  this message  to occur.   However,  an option
exists to allow  you to  bypass the  message and  delete the  receivers
even though they  have not been saved.   This should only be  used when
you  understand  the  recovery  considerations  of the  system  objects
which is discussed in the section on Journal usage.

MTNJRN  also supports  SAVINQMSG(*BYPASS) which  automatically bypasses
any journal  receivers  that  have not  been  saved or  only  partially
saved.  This avoids the inquiry messages.

MTNJRN Data Area in QTEMP
-------------------------

If  a  single  journal is  specified,  the  MTNJRN  data area  will  be
created in QTEMP with the following data structure.

            1 - 10  New receiver name
           11 - 15  Number of deleted receivers
           16 - 28  Amount of deleted receiver storage
           29 - 33  Number of existing receivers

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

   JRN           The  qualified name of  the journal to  be cleaned up.
                 The special  value  *ALLSTD cleans  up  the  following
                 system  journals (the  individual  special values  may
                 also be specified).

                     Journal               Special value
                     -------               -------------

                     QAOSDIAJRN            *OFFICE
                     QDSNX                 *DSNX
                     QSNADS                *SNADS
                     QSXJRN                *PROB
                     QZMF                  *MAIL

                 *ALLSTD  does not provide for  control of the journals
                 QAUDJRN and QACGJRN.   This is  done intentionally  so
                 that  you  may  control  the   attached  receivers  in
                 conjunction with any analysis programs.

                 Other  standard journals supplied  by the  system such
                 as  QLZALOG and QMAJRN are  not supported because they
                 receive little activity.

   GENNEWRCVR    Whether to generate  a new receiver.   The default  is
                 *NO.   Either  this  parameter or  DLTOLDRCVR must  be
                 *YES.      Normally,   you   will   want  to   specify
                 GENNEWRCVR(*YES) before a full  backup of QUSRSYS  and
                 QDOC.

   DLTOLDRCVR    Whether  to delete  old  receivers.   The  default  is
                 *NO.    Either this  parameter or  GENNEWRCVR  must be
                 *YES.     Normally,   you   will   want   to   specify
                 DLTOLDRCVR(*YES) after  a  full backup.   An  attached
                 journal  receiver  (the  active  receiver)  cannot  be
                 deleted.     For  the  other  journal  receivers,  the
                 RETAINDAYS  and RETAINTYPE  parameters  control  which
                 journal receivers will be deleted.

                 A  special   option  of  *TEST  may   be  entered  for
                 DLTOLDRCVR  to allow  a  determination of  what MTNJRN
                 would  do  if   *YES  was   specified.    No   journal
                 receivers  would be  deleted,  but  the final  message
                 would   describe   what   would   have   happened   if
                 DLTOLDRCVR(*YES)   had    been    specified.        If
                 DLTOLDRCVR(*YES)  is  specified,  GENNEWRCVR  must  be
                 *NO.

   RETAINDAYS    The  number   of  days  to   retain  existing  journal
                 receivers.    The default  is 1  day.   The  number of
                 days  specified   is  used   to  calculate  the   last
                 retention date.

                 The  last retention  date  is compared  to either  the
                 attach  date  (the  default)  or  the  detach date  as
                 determined by the RETAINTYPE  parameter.  If both  the
                 RETAINDAYS and  RETAINTYPE are defaulted,  any journal
                 receivers  attached  yesterday  that  are  not  in  an
                 ONLINE status would be deleted.

                 If you want  to keep  more than  the attached  journal
                 receiver  online, you  would  normally specify  a  day
                 which  is  1  greater  than  the date  the  previously
                 attached    journal   receiver    was   attached   (or
                 detached).

                 If you  run MTNJRN every  day or  every week and  want
                 only  the attached receiver  online, the  defaults for
                 both RETAINDAYS and RETAINTYPE are appropriate.

                 If  you want one weeks worth  of receivers online, use
                 a value  such  as  8  regardless of  whether  you  run
                 MTNJRN every day or once a week.

   RETAINTYPE    Whether the  RETAINDAYS parameter should refer  to the
                 attach date or the detach date.

                 *ATTACH  is the  default to use  a comparison  of when
                 the receiver was first attached.

                 *DETACH may be specified to  use a comparison of  when
                 the receiver was detached.

   SAVINQMSG     Whether the  system message should  occur if  a delete
                 journal  request  is made  and  the  receiver has  not
                 been  saved.   The  default is  *YES meaning  that you
                 will receive  a  message.   If  *NO is  specified,  be
                 sure  you understand  the implications  of deleting  a
                 receiver  that  has  not  been  saved  (see the  later
                 section on journal usage).

                 *BYPASS  may  be  specified  to  bypass  the   inquiry
                 message if  the journal  receiver has  not been  saved
                 or  partially saved (no  action occurs  on the journal
                 receiver).

   IGNEXITPGM    A *YES/*NO parameter  for whether to  ignore the  exit
                 program      registered      for       exit      point
                 QIBM_QJO_DLT_JRNRCV.

                 *NO is the default to allow the exit program.

                 *YES  may be  specified  to ignore  the  exit program.
                 DLTOPT(*IGNEXITPGM)   is   passed  to   the  DLTJRNRCV
                 command.

   IGNTGTRCV     A *YES/*NO  parameter  for whether  to ignore  that  a
                 remote   journal   receiver   which   is   immediately
                 downstream  on  a  target  system  be  required  to be
                 full.

                 *NO  is  the   default  which   requires  the   target
                 receiver to be full.

                 *YES may  be specified  to ignore  whether the  target
                 receiver  is full.    DLTOPT(*IGNTGTRCV) is  passed to
                 the DLTJRNRCV command.

   SEQOPT        Specifies  whether  the  journal  sequence  number  is
                 continued   from  the   currently   attached   journal
                 receiver  or the journal  sequence number is  reset to
                 1 in the newly attached journal reciver.

                 *CONT  may be  specified for the  new journal sequence
                 numbers to continue  to be one  greater than the  last
                 journal entry created.

                 *RESET  will  cause the  first  journal  entry in  the
                 newly  attached  journal reciever  to be  reset  to 1.
                 *RESET if  not valid  if  any object  being  journaled
                 contains  changes that  have not  yet  been forced  to
                 auxiliary  storage,   or  if  any  commitment  control
                 changes associated with the journal are pending.

                 GENNEWRCVR(*YES)    must     be     specified     with
                 SEQOPT(*RESET).

                 SEQOPT(*RESET)  may   only  be  specified   for  named
                 receivers, not for any of the special values.

Journal usage
-------------

In   the   following   description,   typical   save   strategies   are
recommended.   You may tailor  this to meet your  individual needs.  In
general, it is  desirable to treat all  of the journals identically  to
simplify your approach.   Changing the receiver even  though no entries
have  occurred (e.g.   you are not  using DSNX) is a  minor overhead on
the system.

The following  journal  objects  are  in QUSRSYS  and  are  shipped  as
standard with the system.

  **   QAOSDIAJRN.  This  journal is used in the running  of office and
       the  handling of  mail.   PC  Support also  adds  documents into
       QDOC which are handled  by the journal.   If you are  performing
       a lot of  office or PC  Support activity, the receivers  will be
       added  to frequently  and you  may need  to change  the receiver
       more than weekly.

       The  receiver  should  be  backed up  regularly  to  provide for
       proper  recovery.    If  recovery  must  be  performed,  several
       situations  may occur  which will  dictate what  to do  with the
       journal.    In  a  disaster  recovery  situation, the  following
       steps are recommended:

           - Restore QUSRSYS (by itself or as part of RSTLIB *NONSYS
           - Restore the last changes (if any to QUSRSYS)
           - RCLDLO to reset the files in QUSRSYS
           - RSTDLO (last full save)
           - RSTDLO (last changes)

       If you use a SAVSTG approach:

           - Restore the SAVSTG media
           - Restore the last changes (if any to QUSRSYS)
           - RCLDLO to reset the files in QUSRSYS
           - RSTDLO (last changes)

       It is  important to  run  RCLDLO before  using RSTDLO.    RCLDLO
       resets the  files in  QUSRSYS which will  be updated  by RSTDLO.
       If  the files are not  reset, RSTDLO will fail  when it attempts
       to add records  to the files  in QUSRSYS for  the new  documents
       being added by the restore.

       Note that  in a disaster  recovery situation,  you do not  apply
       the journal  changes.  The files being  journaled are brought up
       to  date by the  RSTDLO command.   If you have  damage to one of
       the files being journaled,  the ability to apply the  journal to
       a restore of the file is important.

       A  typical solution  (whether you  use office  or PC  Support or
       not)  would  be to  change  the receiver  weekly  in conjunction
       with a full backup.  The  old receiver can be deleted after  the
       full backup.

  **   QSXJRN.  This  journal is used in conjunction  with problem logs
       that  are  kept  in  QUSRSYS.    If  the  files are  deleted  or
       damaged, the  ability  to track  problems  will be  lost.    The
       recommended period  of retention of  a problem is  30 days.   As
       long as you  have the ability to recover  the files for the last
       30 days, you will meet the recommendation.

       A  typical solution  would be to  change the  receiver weekly in
       conjunction  with a  full  backup.    The old  receiver  can  be
       deleted  after the  full backup.    Retain the  receivers and  a
       version   of  the   full  backup  for   a  month   to  meet  the
       recommendation.

  **   QDSNX.  This  journal is used for  an audit trail  of DSNX.   No
       recovery action can be performed with the journal.

       A typical  solution (whether you  use DSNX or  not) would  be to
       change  the receiver weekly  in conjunction with  a full backup.
       The old receiver can be deleted after the full backup.

  **   QSNADS.   This journal  is  used for  an  audit trail  of  SNADS
       activity.    No  recovery  action  can  be  performed  with  the
       journal.

       A typical  solution (whether you  use SNADS or not)  would be to
       change  the receiver weekly  in conjunction with  a full backup.
       The old receiver can be deleted after the full backup.

  **   QZMF.   This journal  is used  for an  audit trail  of mail  log
       activity.    No  recovery  action  can  be  performed  with  the
       journal.

       A  typical solution (whether  you use  mail or not)  would be to
       change the receiver  weekly in conjunction  with a full  backup.
       The old receiver can be deleted after the full backup.

Handling of the inquiry message
-------------------------------

If  the  SAVINQMSG(*NO)  function is requested, the MTNJRN command will
save   the  job's  current  value  for  INQMSGRPY  and  specify  CHGJOB
INQMSGRPY(*DFT).  This  causes the default (I = Ignore) for the message
which must normally be responded to. The job's prior value of INQMSGRPY
is then returned at the end of the command.

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

None

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

The following TAA Tools must be on your system:

     ADDDAT           Add date
     CVTJRNA          Convert journal attributes
     EDTVAR           Edit variable
     SNDCOMPMSG       Send completion message
     SNDESCMSG        Send escape message
     SNDSTSMSG        Send status message

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

None, the tool is ready to use.

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

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

   MTNJRN        *CMD                       TAAJRNC       QATTCMD
   TAAJRNCC      *PGM           CLP         TAAJRNCC      QATTCL
					

Added to TAA Productivity tools April 1, 1995


Home Page Up to Top