TAA Tools
SAVWHLACT       SAVE WHILE ACTIVE                      TAASAVE

         *                                                *
         *    This tool is now obsolete.  You should      *
         *    be using the system support directly or     *
         *    the SAVACT tool.                            *
         *                                                *

The SAVWHLACT command allows a  data base file to be saved  while it is
active.   Being active means that  the file is open for  update and one
or  more  programs  are making  changes  while  the save  occurs.   The
companion command  RSTWHLACT  does  a restore  from  the copy  made  by
SAVWHLACT.  Then it applies changes which occurred during the copy.

These commands  are specifically designed for  those environments where
the  file should be available  for update around the  clock.  When this
type  of  situation  exists,  the  installation  typically  requires  a
window of time  in the wee hours of  the morning to be  used for backup
when  users must signoff or  be kept out  of an application  area.  The
SAVWHLACT command allows  you to get  rid of the window  and makes  the
file available all of the time.

The file being saved  must be journaled.  The journal  changes are used
to  bring the file  back to a  proper state.   It is possible  to start
journaling  just prior  to SAVWHLACT and  then to  end journaling after
the  command  completes.    However,  the  start   and  end  journaling
commands require the  file to be exclusively allocated.   See the later
comments about temporarily journaling the file.

The  SAVWHLACT command  does not  save the  file offline  or to  a save
file.  It only  makes a copy  of the file  that along with the  journal
receiver can be saved to produce an offline backup of the file.

To use  the SAVWHLACT command  you must create  a backup  library where
the  file/members can  be  saved (copied)  to.   The  file/members must
exist prior to executing the command.

This library must  also contains  the files WHLACTP  and WHLACTL  which
describe the files being  used.  The WHLACTP and WHLACTL  files must be
created by the CRTWHLACT command.

A typical use of the SAVWHLACT command would be:


The  command   copies  the  data  from  the   files  specified  to  the
corresponding  file/members in  the backup  library.   The WHLACTP file
is updated to  describe the files copied  and the beginning and  ending
journal  sequence numbers.   These  sequence  numbers are  used by  the
RSTWHLACT command.  The corresponding RST command would be:


The  RST  command copies  the  file back  and then  uses  the APYJRNCHG
command to  bring the files  back to  the same  point.   While the  RST
command is executing, the file is exclusively locked.

When the  SAVWHLACT command is  executed, the current  journal sequence
is saved  just prior to copying each file.   When the copy is complete,
the current journal  sequence number  is also  saved for  informational
purposes.   When the  command completes,  the current journal  sequence
number  is also saved.   This last  sequence number denotes  the common
synch point to recover all files to.

When  the  RSTWHLACT command  is executed,  the copy  back is  done and
then the  APYJRNCHG command is  issued from  the sequence number  where
the  original  copy  was   started  from,  to  the  command  completion
sequence  number.  This has the effect  of bringing all files specified
on the RST back  to a common synch point  (This assumes that all  files
restored  with the  same  RST  command were  saved  with  the same  SAV
command).   The  intent of  this approach  is to  provide for  a common
restart point if it is necessary to recover the files.

The backup copy made is done  by CPYF with COMPRESS(*NO).  This  causes
an exact match  of the file in  terms of relative record numbers.   Any
deleted  records in  the FROM  file become  deleted  records in  the TO
file.   This  ensures that  the proper  relative record numbers  can be
used by the APYJRNCHG command.

During the execution of  the APYJRNCHG command, some errors  may occur.
For example, if  a record is deleted after the  copy starts, but before
the  deleted record number  is accessed  by the copy,  a deleted record
will appear  in the  backup version.   When  the  APYJRNCHG command  is
executed, the  journal entry for  the delete  will attempt to  delete a
deleted  record which  will cause  an error.   The RST  command assumes
that any such errors  which occur during  the from/to sequence  numbers
specified will be  ignored.  The APY  command is restarted at  the next
sequence number.

Rebuilding of access paths

When the  RSTWHLACT command executes, any access  paths on the original
file  will be  rebuilt.   This is  a consideration  in the use  of this
approach on very large files with many access paths.

For example, when  a system save command  executes, you have an  option
to  save access  paths.   This  is  generally desirable  to reduce  the
amount  of time if  a restore  is needed.   Because CPYF  is being used
with SAVWHLACT, the access path  of the original file cannot be  saved.

If the  benefits of saving while  active are significant, it  may still
be a  good choice to use  the function on large files  if the number of
restores expected is small.

Differences with the SAV command SAVWHLACT function

The following reviews the major differences:

  **   The TAA Tool only supports data base physical files.

  **   The TAA Tool requires the files to be journaled.

  **   The  TAA   Tool  does   not  provide   for  commitment   control

  **   The  TAA  Tool  will  rebuild  access  paths  when  the  restore
       function  is used.    The SAV  commands  allow a  saving  of the
       access paths so rebuilding can be avoided on a restore.

  **   The  system function  causes a  seize (everyone  using a library
       is locked out  until the  seize completes).   The TAA Tool  does
       not lock out anyone.

  **   The  system function supports  commitment control,  but requires
       users  to be at  a quiet  point before the  save can  begin.  In
       extreme instances this  can be a  long time or  may never  occur
       (the  system  function  supports  a  timeout  value).    A  user
       completing  a  commitment control  boundary will  be  locked out
       until all  users  have reached  a  quiet point  or  the  timeout

  **   The  TAA Tool  is  not  library sensitive.    The files  can  be
       anywhere and recovery should occur normally.

CRTWHLACT command parameters                          *CMD

   LIB           The library to create the files in.

   SRCLIB        The source  library to use for the  QATTDDS file.  The
                 default  is *TAAARC which  means to use  the source in
                 the TAA Archive.

SAVWHLACT command parameters                          *CMD

   FILE          This is a  list of up to  40 file/members that may  be
                 specified.   Note that if a  multi-member file exists,
                 you  must  name each  member.   The  file/members must
                 exist in the  backup library.   Each  file named  must
                 be journaled  and all  files on  a given command  must
                 be journaled  to the same journal.   Each list is made
                 up of the following elements:

        FILE          The file name to be saved.

        LIB           The library  containing the  file.   The  default
                      is *LIBL.

        MBR           The member of  the file.  The default  is *FIRST.

   BACKUPLIB     The  backup library  to be  used.   This  library must
                 contain   the  file/member   specified  on   the  FILE
                 parameter   and  the   files   WHLACTP   and   WHLACTL
                 described in the implementation steps.

   DLTDAYS       This  parameter provides  for automatic  housecleaning
                 of  the WHLACTP file.  The  default is 30 meaning that
                 any entries made to the  file that are 30 days old  or
                 older will be deleted.

RSTWHLACT command parameters                          *CMD

   FILE          This is  a list of up  to 40 file/members that  may be
                 specified.   Note that if  a multi-member file exists,
                 you must name each member.   The file/members will  be
                 allocated  to  *EXCL  during  the  command  execution.
                 Each list is made up of the following elements:

        FILE          The file name to be restored.

        LIB           The  library containing  the file.    The default
                      is *LIBL.

        MBR           The  member of the file.   The default is *FIRST.

   BACKUPLIB     The backup  library to  be  used.   This library  must
                 contain   the  file/member   specified  on   the  FILE
                 parameter  and the files  WHLACTP and  WHLACTL used by

Parameter notes

Note that the default  for both commands is  MBR(*FIRST).  The  WHLACTP
file  will  describe  the  data  by  this  name.    If  MBR(*FIRST)  is
specified  on SAVWHLACT, it must  also be specified on  RSTWHLACT.  The
file WHLACTP  contains  both the  MBR  name specified  on  the  command
(i.e.  it  could be *FIRST)  and the actual  member used.  It  would be
possible  to  modify  the information  in  the  WHLACTP  file prior  to
executing  the  RSTWHLACT command  if *FIRST  is  no longer  the proper

Recovery steps

If the file  to be  recovered is still  on the  system, is not  damaged
and is  being journaled,  the RSTWHLACT command  can be  issued without
performing a restore or CLRPFM.

If  the  file  is  not being  journaled,  but  is  the  same file  that
SAVWHLACT was  executed  against, you  may  restart journaling  to  the
same journal and have RSTWHLACT operate successfully.

If  the file  has  been deleted,  you must  restore  the original  file
before  executing the  RSTWHLACT command.   The  file you  restore must
have been saved  while the file  was being journaled (i.e.   after  the
STRJRNPF command).  This  is a standard restriction with  the APYJRNCHG
command  that   it  will  only  operate  against   the  file  that  was
originally journaled.

When  journaling is started, an internal  journal ID is assigned to the
file that  must  match a  similar  entry in  the  journal in  order  to
execute the APYJRNCHG  command.  The journal ID is  saved with the file
and  reused on  a restore.    The journal  ID assigned  is based  on an
algorithm including  such things  as the  machine serial  number and  a
consecutive number  assigned for each  journal, etc.   If the  file has
not  been deleted and  the file was  previously assigned a  journal ID,
it  is  reused.    Therefore,  if  the  same  file  still  exists   but
journaling is started,  ended and then  restarted, the same  journal ID
will be used and the APY command can be used successfully.

If  a mismatch  occurs, you  can still  recover the  file by  doing the

  1.   Use   CPYF  to  restore  the  backup  version  from  the  backup
       library.       Specify   COMPRESS(*NO)   MBROPT(*REPLACE)    and

  2.   Display  the  contents of  the  WHLACTP  file  to determine  the
       starting  and ending  journal  sequence numbers  to be  used for
       the file/member desired.   Use these  sequence numbers to  build
       an output file with the DSPJRN command.

  3.   Have  a  user application  apply  the  journal entries  for  the
       specific  file.  An  example of such  a program and  an approach
       which can be used is the APYUSRCHG TAA Tool.

In general,  it would  be a  good practice  to be  ready to  execute  a
command like APYUSRCHG in case of any problems that might occur.

Audit trail

The WHLACTP file contains  several fields that may be  useful for audit
trail  purposes.  You  will need  to write  a display or  print program
for this file or use query.

Journal  entries are also made during the  execution of the SAV and RST
commands to provide a better  audit trail.  The SNDJRNE TYPE  codes are
as follows:

     SS    SAVWHLACT started
     SC    CPYF started
     SE    CPYF ended
     SN    SAVWHLACT normal completion

     RS    RSTWHLACT started
     RC    CPYF back started
     RN    RSTWHLACT normal completion

Temporarily journaling the files

When  the SAVWHLACT  command executes,  it  ensures the  file is  being
journaled.     It  is  possible  to  specify  STRJRNPF  just  prior  to
executing the SAVWHLACT  command and  then ENDJRNPF  after the  command
completes.  However,  both commands require exclusive use  of the file.
The RSTWHLACT  command can be used to recover the  file if the file has
not been recreated since journaling ended.   The file must be  actively
being journaled in order to execute RSTWHLACT.

Year 200 Implications

SAVWHLACT cannot  begin in  one century  and end in  another.   Because
the format  of the journal entries used have  only 6 character dates, a
error  message will be sent  if the century boundary  is crossed.  Note
that  this  is  only  a  restriction  if  the  command  started  before
midnight of 12/31/99 and ended in the following year.

RSTWHLACT  can be  used to  restore  from a  save which  occurred in  a
previous century.


The following TAA Tools must be on your system:

      ADDDAT        Add date
      EXTLST        Extract list
      RTVPFA        Retrieve physical file attributes
      SNDCOMPMSG    Send completion message
      SNDESCMSG     Send escape message
      SNDSTSMSG     Send status message
      TAAARC        TAA Archive


The tool  is ready to use, but you must  first create the files used by
the tool (WHLACTP and WHLACTL)  into the same library where the  backup
files will be placed.  Use the command:

      CRTWHLACT     LIB(xxx)

Objects used by the tool

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

*  WHLACTP       *FILE         PF          TAASAVEP       QATTDDS
*  WHLACTL       *FILE         LF          TAASAVEL       QATTDDS
   SAVWHLACT     *CMD                      TAASAVE        QATTCMD
   RSTWHLACT     *CMD                      TAASAVE2       QATTCMD
   CRTWHLACT     *CMD                      TAASAVE3       QATTCMD
   TAASAVEC      *PGM          CLP         TAASAVEC       QATTCL
   TAASAVEC2     *PGM          CLP         TAASAVEC2      QATTCL
   TAASAVEC3     *PGM          CLP         TAASAVEC3      QATTCL
   TAASAVER      *PGM          RPG         TAASAVER       QATTRPG

* These files will exist in the library specified on CRTWHLACT.


     TAASAVEC3  CL pgm

     TAASAVE   CL pgm
       TAASAVER   RPG pgm

     TAASAVE2  CL pgm
       TAASAVER  RPG pgm

Backup library implementation

  1.   Create a  library for your  backup files  or select one  of your
       existing  libraries to be used  for backup.   The library cannot
       contain any of the  file/members that you  intend to specify  on
       SAVWHLACT.     You  may   have  multiple   libraries  used   for
       SAVWHLACT,  but each  must have  the  WHLACTP and  WHLACTL files
       specified in the next steps.

       Use  the command CRTWHLACT  to create WHLACTP  and WHLACTL files
       in the same library.

  2.   Create the  file/members in  your backup library  that you  want
       to backup.   The TAA  Tool DUPFILFMT would  be a good  choice to
       create  a  duplicate  file.   You  will  normally  not  want the
       backup file  to be  keyed as  this will  slow down  the time  it
       takes to do the backup because an access path must be built.

       The DUPFILFMT command  creates a member of the same  name as the
       file.   The record capacity of  the current file is  used as the
       first element  of the  SIZE parameter  for the  new  file.   Ten
       percent  of the  record capacity  is  used as  the  size of  the
       increment and the number of increments is set to 3.

You are now ready to execute the SAVWHLACT command.

Added to TAA Productivity tools April 1, 1995

Home Page Up to Top