TAA Tools
SAVFARC         SAVE FILE ARCHIVE                      TAASAWI

The  Save  File Archive  tool  is  a  series of  commands  that  allows
archiving  of save files.   This provides  an online solution  for save
files  to allow a restore of  saved information without having to mount
media.  The sub  tools WRKSAVFOBJ and WRKSAVFMBR  may be used to  allow
an option for restore rather than entering complex commands.

The objects in the archive are *FILE types with *SAVF attributes.

Overview
---------

Control  files  must be  created  first  with  the CRTSAVFARC  command.
Before  a save file  can be archived,  a master record  must be created
using the WRKSAVFARM (Work  Save Archive Master)  command.  An ID  must
be assigned  (6 characters) and a  maximum number of versions  to allow
automatic cleanup.

A  version  of  the  save  file  is  placed  in  the archive  with  the
ADDSAVFARC command.    For example,  assume  you want  to  archive  the
contents of  the  ABC save  file everyday  after a  save has  occurred.
You  would use WRKSAVFARM  once to describe  the master record  for the
save  file.   After a  SAVxxx command  is used  to save objects  to the
save file,  the ADDSAVFARC  command  would be  used to  place the  save
file into the archive.

The  WRKSAVFARC command  may  be used  to  review the  save files  that
exist  in  the archive.    Options exist  from the  display  to restore
either by library or by object.

Cleanup of old  save files  in the archive  occurs automatically  based
on the number specified to be retained.

Getting started
---------------

This  section describes  a  demonstration of  the  SAVFARC  tool.   You
should  follow  these   same  steps  in  setting  up  and  operating  a
production version.

  **   For demonstration purposes,  create the  save file  ABC in  some
       library.

            CRTSAVF    FILE(xxx/ABC) TEXT('Used for SAVFARC demo')

  **   Save the contents of an object to the save file such as:

            SAVOBJ     OBJ(TAAATNAC) LIB(TAATOOL) DEV(SAVF)
                         SAVF(xxx/ABC)

  **   Create a unique library  for the SAVFARC control files  and save
       files.

             CRTLIB     LIB(TSTSAVFARC) TEXT('SAVFARC demonstration')

       For  demonstration  and  production  use,  a unique  library  is
       preferable.

  **   Use CRTSAVFARC:

             CRTSAVFARC SAVFARCLIB(TSTSAVFARC)

  **   Use DSPLIB to see the control files:.

             DSPLIB     LIB(TSTSAVFARC)

       There  should be  two physical  files (SAVARCMST  and SAVARCDTL)
       and two logical files (SAVARCMSTL and SAVARCDTLL).

  **   Enter WRKSAVFARM for the library:

             WRKSAVFARM  SAVFARCLIB(TSTSAVFARC)

  **   Use F6 to add  a description record for  the save file that  you
       want to  archive.  The  description record is the  master record
       of  what you  intend to  save.   For example,  if you  save SAVF
       'ABC' every  day, you  need one  master record  even though  you
       may have many versions of the save file.

       The 'Save ID'  field must be 6 characters  (no trailing blanks).
       If  you intend  to save library  ABC to  a save file,  a typical
       'Save ID' would be ABCXXX.   When a save  file is placed in  the
       archive  for  ABCXXX,  it   would  be  given  a  name   such  as
       ABCXXX0001.

       For demonstration purposes, enter:

          Save ID            ABCXXX
          Max versions       2
          Text description   ABC save file

  **   Press F3  to return to  the subfile display and  the ABCXXX Save
       ID description should appear.

  **   End WRKSAVFARM by using F3.

  **   ADDSAVFARC  is  the command  that places  a  save file  into the
       archive.  The existing save file is always renamed.

       The ADDSAVFARC ACTION parameter has 3 choices:

         --   *MOV - Will move the  save file to the archive.   This is
              the  fastest solution,  but  normally  requires that  you
              use  CRTSAVF prior  to  each save  to a  save file.   The
              save file will be renamed in the archive.

         --   *MV2 - Like *MOV,  but will also create  a new save  file
              where the original  save file was moved from.   This just
              avoids  your code having  to create  the save file.   The
              save file will be renamed in the archive.

         --   *DUP -  This  will  duplicate  the  save  file  into  the
              archive  using CRTDUPOBJ.   This  is  slower, but  allows
              you  to retain the  original save file  as is.   The save
              file will be renamed in the archive.

       Add the save file to the archive using the *DUP action:

             ADDSAVFARC  SAVF(xxx/ABC) SAVID(ABCXXX)
                          ACTION(*DUP) SAVFARCLIB(TSTSAVFARC)

       The  save file  would be duplicated  to the archive  and given a
       new name of ABCXXX0001.

       You cannot add  an empty save  file to the  archive.  An  escape
       message (TAA9892) is  sent in this case.   This protects against
       a  situation where the save  to the save file  did not occur and
       the archive version is meaningless.

  **   Add the same  save file by  duplicating the ADDSAVFARC  command.
       Each time  ADDSAVFARC is used, the  last name for the  same Save
       ID  is determined  and  the next  number would  be  assigned (in
       this case ABCXXX0002).

  **   Add the same  save file  by duplicating  the ADDSAVFARC  command
       again.   The ABCXXX0003  name would  be assigned.   Because  the
       number of  versions exceeds the  number you specified  (2 in the
       example),  the oldest  version would  be deleted  thus keeping 2
       versions online.

  **   Each time ADDSAVFARC  is used, a detail  record is added to  the
       SAVARCDTL file that  corresponds to the save file  placed in the
       archive.   Use WRKSAVFARC to  look at the detail  records in the
       archive.

             WRKSAVFARC

       The  WRKSAVFARC   command  allows   several  options   such   as
       displaying the  heading information, using the  DSPSAVF command,
       or one of the options to restore the data.

       You  can prompt  for the RSTOBJ  or RSTLIB  commands.   Option 3
       will  invoke  the  WRKSAVFOBJ  command  which  provides  a  work
       display  for the  saved  objects.    An option  from  WRKSAVFOBJ
       provides  a work  display  of members  in  a data  base  file to
       allow a simple restore.

  **   You  can  toggle between  the two  WRK displays.   If  you start
       with WRKSAVFARC, you can  operate on the detail save  records by
       using Option  8.  If you  start with WRKSAVFARC, you  can use F6
       to access WRKSAVFARM.

       If  you toggle to the  next display, you must  use F3 to return.

  **   You should not attempt  to create a  save file that follows  the
       SAVFARC  technique  for   naming  another  version.     Use  the
       ADDSAVFARC   command  which   will  create  the   proper  naming
       convention and add a record to the detail file.

  **   To delete  a save  archive description,  you must  first  delete
       the individual  save files  (if any)  for the same  ID by  using
       the  WRKSAVFARC command.   Then  the  WRKSAVFARM command  may be
       used to delete the save archive master record.

Other SAVxxx commands
---------------------

Save  files supported by SAVOBJ and  SAVLIB are fully supported and may
be restored  by the  corresponding command.   RSTOBJ may  also be  used
for save files saved by SAVLIB.

Save files saved by the SAV command are not supported.

Save  files saved  by commands  such as  SAVDLO, SAVCFG,  and SAVSECDTA
may  be placed in the Save Archive  by using ADDSAVFARC.  However, only
RSTOBJ and RSTLIB options are supported from WRKSAVFARC.

It is  possible to use  a command  such as  RSTCFG directly  on a  save
file  saved  by  SAVCFG  that  was   placed  in  the  Save  Archive  by
ADDSAVFARC.

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

    - CRTSAVFARC   - Creates the save files required for the archive
    - DLTSAVFARC   - Deletes the save files required for the archive
    - WRKSAVFARM   - Works with the master description records
    - ADDSAVFARC   - Adds a save file to the archive
    - WRKSAVFARC   - Works with the detail save file records
    - ADDSAVFARM   - Add a save archive master description
    - RTVSAVFARC   - Retrieve save archive save file description

Files
-----

    - SAVARCMST     PF    TAASAWIP
    - SAVARCMSTL    LF    TAASAWIL
    - SAVARCDTL     PF    TAASAWIQ
    - SAVARCDTLL    LF    TAASAWIL

CRTSAVFARC escape messages you can monitor for
----------------------------------------------

None.  Escape messages from based on functions will be re-sent.

DLTSAVFARC escape messages you can monitor for
----------------------------------------------

      TAA9891    Not all save files could be deleted.

Escape messages from based on functions will be re-sent.

WRKSAVFARM escape messages you can monitor for
----------------------------------------------

None.  Escape messages from based on functions will be re-sent.

ADDSAVFARC escape messages you can monitor for
----------------------------------------------

      TAA9891    The save file does not exist
      TAA9892    The save file is empty
      TAA9893    ADDSAVFARC found errors

Escape messages from based on functions will be re-sent.

WRKSAVFARC escape messages you can monitor for
----------------------------------------------

None.  Escape messages from based on functions will be re-sent.

ADDSAVFARM escape messages you can monitor for
----------------------------------------------

      TAA9895    Duplicate Save ID exists

Escape messages from based on functions will be re-sent.

RTVSAVFARC escape messages you can monitor for
----------------------------------------------

      TAA9896    The Save ID does not exist

Escape messages from based on functions will be re-sent.

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

   SAVFARCLIB    The  name  of  the  library  where  the  Save  Archive
                 control files  will be  created.   The physical  files
                 SAVARCMST  and   SAVARCDTL  are  created   along  with
                 logical files over each.

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

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

   AUT           The authority to the  physical files.  The default  is
                 *USE which allows any user to use the files.


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

   SAVFARCLIB    The  name  of  the  library  where  the  Save  Archive
                 control  files exist.  Both the  control files and any
                 save files created by ADDSAVFARC will be deleted.


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

   SAVFARCLIB    The  name  of  the  library  where  the  Save  Archive
                 control  files  exist.    *LIBL is  the  default.    A
                 specific library or *CURLIB may be entered.

   OUTPUT        How  to  output the  results.   *  is  the  default to
                 display a subfile of the save IDs.

                 If the  command  is  entered in  batch  or  *PRINT  is
                 specified, a  spooled file  is output  with the  basic
                 information.

   CALLFROM      How the  command was invoked.  This  is intended to be
                 an  internal use  function and  defaults to  *CMD.  It
                 is used by WRKSAVFARM to prevent recursion.


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

   SAVID         The  ID  of   the  save  file  description   (not  the
                 version).   This is the  starting value as  if entered
                 for the 'position to' value on the display.

                 *ALL  is   the  default  to  display  all  the  detail
                 records.

                 A specific ID  may be  entered to  display just  those
                 detail records that match the Save ID.

   SAVFARCLIB    The name  of the library  where the Save  Archive File
                 control  files  exist.    *LIBL  is  the default.    A
                 specific library or *CURLIB may be entered.

   OUTPUT        How to  output  the results.    * is  the  default  to
                 display a subfile of the save IDs.

                 If  the command  is  entered  in  batch or  *PRINT  is
                 specified,  a spooled  file is  output with  the basic
                 information.

   CALLFROM      How  the command was invoked.   This is intended to be
                 an internal  use function and  defaults to  *CMD.   It
                 is used by WRKSAVFARC to prevent recursion.


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

   SAVF          The  qualified name of  the save  file that  should be
                 placed into the archive.

   SAVID         The   ID  of  the  save   file  description  (not  the
                 version).

   ACTION        The action to be performed  on the save file named  in
                 the SAVF parameter.   The save file  is always renamed
                 according   to  the  SAVID  plus   4  digits  such  as
                 ABCXXXnnnn.

                 *MOV is  the default  meaning the  save file  will  be
                 moved  to the  Save Archive  Library.   This  probably
                 requires  your code  to create  another save  file the
                 next time a save is required.

                 *MV2  is the same as *MOV  except that a new save file
                 is created where the old one was moved from.

                 *DUP  may be  specified  to  duplicate the  save  file
                 object  into  the  Save  Archive library  with  a  new
                 name.    The  existing  save  file  remains the  same.
                 This is  the  slowest  action  as  CRTDUPOBJ  must  be
                 used.

   SAVFARCLIB    The name  of the library  where the Save  Archive File
                 control  files  exist.    *LIBL  is  the default.    A
                 specific library or *CURLIB may be entered.


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

   SAVID         The  ID  of  the   save  file  description  (not   the
                 version).

   MAXVER        The maximum number  of versions that may exist  in the
                 save archive for this SAVID.

   TEXT          The text description assigned to the Save ID.

   SAVFARCLIB    The name  of the library  where the Save  Archive File
                 control  files  exist.    *LIBL  is  the  default.   A
                 specific library or *CURLIB may be entered.


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

   SAVID         The  ID  of  the   save  file  description  (not   the
                 version).

   VERSION       The  save file version  to be  returned.   The default
                 is  *LAST for  the  newest save  file for  this SAVID.
                 *FIRST may be specified for  the oldest save file  for
                 this SAVID.

   SAVFARCLIB    The name  of the library  where the Save  Archive File
                 control  files  exist.    *LIBL  is  the default.    A
                 specific library or *CURLIB may be entered.

   RTNARCLIB     The name of  the library where  the Save Archive  File
                 Detail file  (SAVARCDTL) was  found.   This may be  of
                 value if  a special value was used  for the SAVFARCLIB
                 parameter.   This is an  optional return variable that
                 if used must be specified as *CHAR LEN(10).

   SAVF          The name of  the save file  in the Save File  Archive.
                 This  is  an optional  return  variable  that if  used
                 must be specified as *CHAR LEN(10).

   ORGSAVF       The  name of the original save  file that was added to
                 the Archive.   This  is  an optional  return  variable
                 that if used must be specified as *CHAR LEN(10).

   ORGSAVFL      The name  of the original  save file library  that was
                 added  to the  Archive.   This  is an  optional return
                 variable that  if  used  must be  specified  as  *CHAR
                 LEN(10).

   SAVFDATE      The date  the save  data was  written to the  original
                 save  file  in  CYMD  format.    This is  an  optional
                 return  variable  that if  used  must be  specified as
                 *CHAR LEN(7).

   SAVFTIME      The time  the save data  was written  to the  original
                 save file.   This is an optional  return variable that
                 if used must be specified as *CHAR LEN(6).

   ARCDATE       The  date  the  save file  was  included  in  the Save
                 Archive in  CYMD  format (when  ADDSAVFARC  was  run).
                 This  is an  optional  return  variable that  if  used
                 must be specified as *CHAR LEN(7).

   ARCTIME       The  time  the  save file  was  included  in the  Save
                 Archive  (when  ADDSAVFARC  was  run).    This  is  an
                 optional  return  variable   that  if  used   must  be
                 specified as *CHAR LEN(6).

   SAVLIB        The  library where the  objects were  originally saved
                 from.   This  is an  optional return  variable that if
                 used must be specified as *CHAR LEN(10).

   SAVCMD        The command  used to  save the  objects.   This is  an
                 optional  return   variable  that  if   used  must  be
                 specified as *CHAR LEN(10).

   NBROBJECTS    The  number of objects  saved in the save  file.  This
                 is an optional  return variable that  if used must  be
                 specified as *DEC LEN(10 0).

   NBRRECORDS    The number of  records in the save file.   Each record
                 is  528 bytes.   This is  an optional  return variable
                 that if used must be specified as *DEC LEN(10 0).

   SIZE          The size  of the  save  file in  bytes.   This  is  an
                 optional  return  variable   that  if  used   must  be
                 specified as *DEC LEN(15 0).

   TEXT          The  text description  assigned  to the  save  file in
                 the  Archive.   This  is  an optional  return variable
                 that if used must be specified as *CHAR LEN(50).


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

  **   A save file  saved by  a SAV command  may not  be placed in  the
       archive.

  **   Only  the RSTOBJ and  RSTLIB commands  are supported  as options
       from  the WRKSAVFARC  display.   Save files  saved by  a command
       such as  SAVCFG may  be placed  in the  archive,  but require  a
       specific restore command be entered.

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

The following TAA Tools must be on your system:

     ADJVAR          Adjust variable
     CHGOBJD2        Change object description 2
     CHKACTOBJ       Check active object
     CHKALLOBJ       Check *ALLOBJ special authority
     CHKNAM          Check name
     CPYTAADDS       Copy TAA DDS
     CVTDAT          Convert date
     EDTVAR          Edit variable
     FILEFDBCK       File feedback
     LOCKMSG         Lock message
     RPGSTSDS        RPG status data structure
     RSNLSTMSG       Resend last message
     RSTSAVFMBR      Restore save file member
     RTVDAT          Retrieve date
     RTVSAVFD        Retrieve save file description
     RTVSYSVAL3      Retrieve system value 3
     SNDCOMPMSG      Send completion message
     SNDDIAGMSG      Send diagnostic message
     SNDESCINF       Send escape information
     SNDESCMSG       Send escape message
     SNDSTSMSG       Send status message
     UPDPFILE        Update PFILE keyword
     WRKSAVFOBJ      Work save file objects

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

None, the tool is ready to use.

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

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

   CRTSAVFARC    *CMD                   TAASAWI       QATTCMD
   DLTSAVFARC    *CMD                   TAASAWI2      QATTCMD
   WRKSAVFARM    *CMD                   TAASAWI3      QATTCMD
   ADDSAVFARC    *CMD                   TAASAWI4      QATTCMD
   WRKSAVFARC    *CMD                   TAASAWI5      QATTCMD
   ADDSAVFARM    *CMD                   TAASAWI6      QATTCMD
   RTVSAVFARC    *CMD                   TAASAWI7      QATTCMD
   TAASAWIC      *PGM       CLP         TAASAWIC      QATTCL
   TAASAWIC2     *PGM       CLP         TAASAWIC2     QATTCL
   TAASAWIC3     *PGM       CLP         TAASAWIC3     QATTCL
   TAASAWIC4     *PGM       CLP         TAASAWIC4     QATTCL
   TAASAWIC5     *PGM       CLP         TAASAWIC5     QATTCL
   TAASAWIC6     *PGM       CLP         TAASAWIC6     QATTCL
   TAASAWIC7     *PGM       CLP         TAASAWIC7     QATTCL
   TAASAWIC21    *PGM       CLP         TAASAWIC21    QATTCL
   TAASAWIC22    *PGM       CLP         TAASAWIC22    QATTCL
   TAASAWIR3     *PGM       RPG         TAASAWIR3     QATTRPG
   TAASAWIR4     *PGM       RPG         TAASAWIR4     QATTRPG
   TAASAWIR5     *PGM       RPG         TAASAWIR5     QATTRPG
   TAASAWIR6     *PGM       RPG         TAASAWIR6     QATTRPG
   TAASAWIR7     *PGM       RPG         TAASAWIR7     QATTRPG
   TAASAWIR21    *PGM       RPG         TAASAWIR21    QATTRPG
   TAASAWIR22    *PGM       RPG         TAASAWIR22    QATTRPG
   TAASAWIR23    *PGM       RPG         TAASAWIR23    QATTRPG
   TAASAWIP      *FILE      PF          TAASAWIP      QATTDDS
   TAASAWIQ      *FILE      PF          TAASAWIQ      QATTDDS
   TAASAWIL      *FILE      LF          TAASAWIL      QATTDDS
   TAASAWIM      *FILE      LF          TAASAWIM      QATTDDS
   TAASAWID      *FILE      DSPF        TAASAWID      QATTDDS
   TAASAWIE      *FILE      DSPF        TAASAWIE      QATTDDS
   TAASAWIF      *FILE      DSPF        TAASAWIF      QATTDDS

Structure
---------

CRTSAVFARC  Cmd
   TAASAWIC    CL pgm

DLTSAVFARC   Cmd
   TAASAWIC2   CL pgm

WRKSAVFARM  Cmd
   TAASAWIC3   CL pgm
     TAASAWIR3   RPG pgm
       TAASAWID     Display file
       TAASAWIR22   RPG pgm  -  Determines next save file name

ADDSAVFARC   Cmd
   TAASAWIC4   CL pgm
     TAASAWIR21   RPG pgm  - Validates Save ID
     TAASAWIR22   RPG pgm  - Determines next save file name
     TAASAWIR23   RPG pgm  - Deletes a detail archive record

WRKSAVFARC   Cmd
   TAASAWIC5   CL pgm
     TAASAWIR5   RPG pgm
       TAASAWIE     Display file
       TAASAWIC21   CL pgm - Does options except for delete
       TAASAWIC22   CL pgm - Does delete option
         TAASAWIF     Display file
         TAASAWIR23   RPG pgm  - Deletes a detail archive record

ADDSAVFARM   Cmd
   TAASAWIC6   CL pgm
     TAASAWIR6   RPG pgm

RTVSAVFARC   Cmd
   TAASAWIC7   CL pgm
     TAASAWIR7   RPG pgm
					

Added to TAA Productivity tools May 15, 2008


Home Page Up to Top